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": "frank.osborne@acmeplc.com"
    },
    "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: "frank.osborne@acmeplc.com"
    },
    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": "frank.osborne@acmeplc.com"
  },
  "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: "frank.osborne@acmeplc.com"
  },
  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" => "frank.osborne@acmeplc.com"
    ],
    "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("frank.osborne@acmeplc.com")
  .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:        "tim@gocardless.com",
    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 = "api@gocardless.com",
    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

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

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

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

Customer's email address.

given_namestring

Customer's first name.

family_namestring

Customer's surname.

company_namestring

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

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department.

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring

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

danish_identity_numberstring

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

prefilled_bank_accountobject

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

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

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

linksobject

1 properties

billing_requeststring

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

Response 201

Resource created successfully

billing_request_flowsobject

19 properties

idstring

Unique identifier, beginning with "BRF".

redirect_uristring

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

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

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

13 properties

emailstring

Customer's email address.

given_namestring

Customer's first name.

family_namestring

Customer's surname.

company_namestring

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

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department.

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring

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

danish_identity_numberstring

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

prefilled_bank_accountobject

1 properties

account_typestring

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

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

linksobject

1 properties

billing_requeststring

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

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

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`required	string	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

idstring

Unique identifier, beginning with "BRF".

redirect_uristring

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

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

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

13 properties

emailstring

Customer's email address.

given_namestring

Customer's first name.

family_namestring

Customer's surname.

company_namestring

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

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department.

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring

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

danish_identity_numberstring

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

prefilled_bank_accountobject

1 properties

account_typestring

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

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

linksobject

1 properties

billing_requeststring

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

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject