Billing Request Flow

View as Markdown

Billing Request Flows can be created to enable a payer to authorise a payment created for a scheme with strong payer authorisation (such as open banking single payments).

Create a Billing Request Flow#

POST/billing_request_flows

Creates a new billing request flow.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/billing_request_flows HTTP/1.1
Content-Type: application/json
{
  "billing_request_flows": {
    "redirect_uri": "https://my-company.com/landing",
    "exit_uri": "https://my-company.com/exit",
    "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "[email protected]"
    },
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

@client.billing_request_flows.create(
  params: {
    redirect_uri: "https://my-company.com/landing",
    exit_uri: "https://my-company.com/exit",
    prefilled_customer: {
      given_name: "Frank",
      family_name: "Osborne",
      email: "[email protected]"
    },
    links: {
      billing_request: "BRQ123",
    }
  }
)

client.billing_request_flows.create(params={
  "redirect_uri": "https://my-company.com/landing",
  "exit_uri": "https://my-company.com/exit",
  "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "[email protected]"
  },
  "links": {
    "billing_request": "BRQ123"
  }
})

const billingRequestFlow = await client.billingRequestFlows.create({
  redirect_uri: "https://my-company.com/landing",
  exit_uri: "https://my-company.com/exit",
  prefilled_customer: {
    given_name: "Frank",
    family_name: "Osborne",
    email: "[email protected]"
  },
  links: {
    billing_request: "BRQ123",
  }
});

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "prefilled_customer" => [
      "given_name" => "Frank",
      "family_name" => "Osborne",
      "email" => "[email protected]"
    ],
    "links" => [
      "billing_request" => "BRQ123"
    ]
  ]
]);

BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()
  .withRedirectUri("https://my-company.com/landing")
  .withExitUri("https://my-company.com/exit")
  .withPrefilledCustomerGivenName("Frank")
  .withPrefilledCustomerFamilyName("Osborne")
  .withPrefilledCustomerEmail("[email protected]")
  .withLinksBillingRequest("BRQ123")
  .execute();

billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams{
  RedirectUri: "https://my-company.com/landing",
  ExitUri:     "https://my-company.com/exit",
  PrefilledCustomer: &gocardless.BillingRequestFlowCreateParamsPrefilledCustomer{
    AddressLine1: "338-346 Goswell Road",
    City:         "London",
    GivenName:    "Tim",
    FamilyName:   "Rogers",
    Email:        "[email protected]",
    PostalCode:   "EC1V 7LQ",
  },
  Links: gocardless.BillingRequestFlowCreateParamsLinks{
    BillingRequest: "BR123",
  },
}

billingRequestFlow, err := client.BillingRequestFlows.Create(ctx, billingRequestFlowCreateParams)

var prefilledCustomer = new GoCardless.Services.BillingRequestFlowCreateRequest.BillingRequestFlowPrefilledCustomer()
{
    AddressLine1 = "338 Goswell Road",
    Email = "[email protected]",
    GivenName = "Bobby",
    FamilyName = "Tables"
};

var resp = await client.BillingRequestFlows.CreateAsync(
  new GoCardless.Services.BillingRequestFlowCreateRequest()
  {
    RedirectUri = "https://my-company.com/landing",
    ExitUri = "https://my-company.com/exit",
    PrefilledCustomer = prefilledCustomer,
    Links = new GoCardless.Services.BillingRequestFlowCreateRequest.BillingRequestFlowLinks
    {
      BillingRequest = "BRQ123",
    },
  }
);

GoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;

Responsehttp

HTTP/1.1 201 Created
Location: /billing_request_flows/BRF123456
Content-Type: application/json
{
  "billing_request_flows": {
    "id": "BRF123456",
    "auto_fulfil": true,
    "redirect_uri": "https://my-company.com/landing",
    "exit_uri": "https://my-company.com/exit",
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=BRF123456",
    "lock_customer_details": false,
    "lock_currency": false,
    "lock_bank_account": false,
    "skip_success_screen": false,
    "session_token": null,
    "expires_at": "2021-07-30T16:25:16.982Z",
    "created_at": "2021-07-23T16:25:16.983Z",
    "links": {
      "billing_request": "BRQ123"
    },
    "show_redirect_buttons": false,
    "show_success_redirect_button": false,
    "customer_details_captured": false
  }
}

Request Body

billing_request_flowsobject

14 properties

auto_fulfilboolean

(Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.

customer_details_capturedboolean

Identifies whether a Billing Request belongs to a specific customer

lock_bank_accountboolean

If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock bank account if these have already been completed as a part of the billing request.

lock_currencyboolean

If true, the payer will not be able to change their currency/scheme manually within the flow. Note that this only applies to the mandate only flows - currency/scheme can never be changed when there is a specified subscription or payment.

lock_customer_detailsboolean

If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock customer details if these have already been completed as a part of the billing request.

show_redirect_buttonsboolean

If true, the payer will be able to see redirect action buttons on Thank You page. These action buttons will provide a way to connect back to the billing request flow app if opened within a mobile app. For successful flow, the button will take the payer back the billing request flow where they will see the success screen. For failure, button will take the payer to url being provided against exit_uri field.

show_success_redirect_buttonboolean

If true, the payer will be able to see a redirect action button on the Success page. This action button will provide a way to redirect the payer to the given redirect_uri. This functionality is helpful when merchants do not want payers to be automatically redirected or on Android devices, where automatic redirections are not possible.

redirect_uristring | null

URL that the payer can be redirected to after completing the request flow.

skip_success_screenboolean

If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.

exit_uristring | null

URL that the payer can be taken to if there isn't a way to progress ahead in flow, for example if the customer searches for a bank that doesn't exist or isn't supported on the scheme.

prefilled_customerobject | null

Customer information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.

13 properties

emailstring | null

Customer's email address.

given_namestring | null

Customer's first name.

family_namestring | null

Customer's surname.

company_namestring | null

Customer's company name. Company name should only be provided if given_name and family_name are null.

address_line1string | null

The first line of the customer's address.

address_line2string | null

The second line of the customer's address.

address_line3string | null

The third line of the customer's address.

citystring | null

The city of the customer's address.

regionstring | null

The customer's address region, county or department.

postal_codestring | null

The customer's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring | null

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.

danish_identity_numberstring | null

For Danish customers only. The civic/company number (CPR or CVR) of the customer.

prefilled_bank_accountobject | null

Bank account information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.

1 properties

account_typestring | null

Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

languagestring | null

Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.

linksobjectrequired

1 properties

billing_requeststringrequired

ID of the billing request against which this flow was created.

Response 201

Resource created successfully

billing_request_flowsobject

19 properties

idstringrequired

Unique identifier, beginning with "BRF".

redirect_uristring | null

URL that the payer can be redirected to after completing the request flow.

skip_success_screenboolean

If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.

exit_uristring | null

URL that the payer can be taken to if there isn't a way to progress ahead in flow, for example if the customer searches for a bank that doesn't exist or isn't supported on the scheme.

show_redirect_buttonsboolean

show_success_redirect_buttonboolean

authorisation_urlstring

URL for a GC-controlled flow which will allow the payer to fulfil the billing request

created_atstring

Timestamp when the flow was created

expires_atstring

Timestamp when the flow will expire. Each flow currently lasts for 7 days.

session_tokenstring | null

Session token populated when responding to the initialise action

auto_fulfilboolean

(Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.

lock_bank_accountboolean

If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock bank account if these have already been completed as a part of the billing request.

lock_currencyboolean

lock_customer_detailsboolean

If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock customer details if these have already been completed as a part of the billing request.

prefilled_customerobject | null

13 properties

emailstring | null

Customer's email address.

given_namestring | null

Customer's first name.

family_namestring | null

Customer's surname.

company_namestring | null

Customer's company name. Company name should only be provided if given_name and family_name are null.

address_line1string | null

The first line of the customer's address.

address_line2string | null

The second line of the customer's address.

address_line3string | null

The third line of the customer's address.

citystring | null

The city of the customer's address.

regionstring | null

The customer's address region, county or department.

postal_codestring | null

The customer's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring | null

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.

danish_identity_numberstring | null

For Danish customers only. The civic/company number (CPR or CVR) of the customer.

prefilled_bank_accountobject | null

1 properties

account_typestring | null

Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

languagestring | null

Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.

linksobject

1 properties

billing_requeststringrequired

ID of the billing request against which this flow was created.

customer_details_capturedboolean

Identifies whether a Billing Request belongs to a specific customer

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

Initialise a Billing Request Flow#

POST/billing_request_flows/{billing_request_flow_id}/actions/initialise

Returns the flow having generated a fresh session token which can be used to power integrations that manipulate the flow.

Path Parameters

Name	Type	Description
`billing_request_flow_id`	stringrequired	The billing request flow id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/billing_request_flows/BRF123/actions/initialise HTTP/1.1

@client.billing_request_flows.initialise("BRF123")

client.billing_request_flows.initialise("BRF123")

const resp = await client.billingRequestFlows.initialise("BRF123");

$client->billingRequestFlows()->initialise("BRF123");

client.billingRequestFlows().initialise("BRF123").execute();

billingRequestFlowInitialiseParams := gocardless.BillingRequestFlowInitialiseParams{}
billingRequestFlow, err := client.BillingRequestFlows.Initialise(ctx, "BRF123", billingRequestFlowInitialiseParams)

var resp = await client.BillingRequestFlows.InitialiseAsync("BRF123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "billing_request_flows":{
      "id":"BRF123",
      "auto_fulfil":true,
      "redirect_uri":null,
      "exit_uri":null,
      "authorisation_url":"https://pay-sandbox.gocardless.com/billing/static/flow?id=BRF123",
      "lock_customer_details":false,
      "lock_bank_account":false,
      "lock_currency": false,
      "skip_success_screen": false,
      "session_token":"sesh_sandbox_DHTMvJAUajbd9KTCoXNFcTv4RSoWdMbauhnalxiqwbdsb",
      "expires_at":"2021-09-01T08:45:38.016Z",
      "created_at":"2021-08-25T08:45:38.017Z",
      "links":{
        "billing_request":"BRQ123"
      },
      "show_redirect_buttons": false,
    "show_success_redirect_button": false,
    "customer_details_captured": false
  }
}

Response 200

Action completed successfully

billing_request_flowsobject

19 properties

idstringrequired

Unique identifier, beginning with "BRF".

redirect_uristring | null

URL that the payer can be redirected to after completing the request flow.

skip_success_screenboolean

If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.

exit_uristring | null

URL that the payer can be taken to if there isn't a way to progress ahead in flow, for example if the customer searches for a bank that doesn't exist or isn't supported on the scheme.

show_redirect_buttonsboolean

show_success_redirect_buttonboolean

authorisation_urlstring

URL for a GC-controlled flow which will allow the payer to fulfil the billing request

created_atstring

Timestamp when the flow was created

expires_atstring

Timestamp when the flow will expire. Each flow currently lasts for 7 days.

session_tokenstring | null

Session token populated when responding to the initialise action

auto_fulfilboolean

(Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.

lock_bank_accountboolean

If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock bank account if these have already been completed as a part of the billing request.

lock_currencyboolean

lock_customer_detailsboolean

If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.

You can only lock customer details if these have already been completed as a part of the billing request.

prefilled_customerobject | null

13 properties

emailstring | null

Customer's email address.

given_namestring | null

Customer's first name.

family_namestring | null

Customer's surname.

company_namestring | null

Customer's company name. Company name should only be provided if given_name and family_name are null.

address_line1string | null

The first line of the customer's address.

address_line2string | null

The second line of the customer's address.

address_line3string | null

The third line of the customer's address.

citystring | null

The city of the customer's address.

regionstring | null

The customer's address region, county or department.

postal_codestring | null

The customer's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring | null

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.

danish_identity_numberstring | null

For Danish customers only. The civic/company number (CPR or CVR) of the customer.

prefilled_bank_accountobject | null

1 properties

account_typestring | null

Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

languagestring | null

Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.

linksobject

1 properties

billing_requeststringrequired

ID of the billing request against which this flow was created.

customer_details_capturedboolean

Identifies whether a Billing Request belongs to a specific customer

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring