Billing Request With Action

View as Markdown

Billing Requests help create resources that require input or action from a customer. An example of required input might be additional customer billing details, while an action would be asking a customer to authorise a payment using their mobile banking app.

See Billing Requests: Overview for how-to's, explanations and tutorials.

Create a Billing Request with Actions#

POST/billing_requests/create_with_actions

Restricted

this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

Note

to modify data on an already created billing request, call individual action endpoints. Calling this endpoint creates a new billing request everytime.

Warning

ACH/PAD is not supported on this endpoint.

Creates a billing request and completes any specified actions in a single request. This endpoint allows you to create a billing request and immediately complete actions such as collecting customer details, bank account details, or other required actions.

HTTP

POST https://api.gocardless.com/billing_requests/create_with_actions HTTP/1.1
Content-Type: application/json
{
  "billing_request_with_actions": {
    "payment_request": {
      "description": "First Payment",
      "amount": "500",
      "currency": "GBP"
    },
    "actions": {
      "collect_customer_details": {
        "customer": {
          "email": "alice@example.com",
          "given_name": "Alice",
          "family_name": "Smith"
        }
      },
      "select_institution": {
        "institution": "IN123",
        "country_code": "GB"
      },
      "create_bank_authorisation": true
    }
  }
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "billing_request_with_actions": {
      "billing_requests": {
      "id": "BRQ123",
      "created_at": "2025-03-06T21:36:43Z",
      "status": "pending",
      "payment_request": {
        "description": "First Payment",
        "amount": 500,
        "currency": "GBP"
      },
      "actions": [
        {
          "type": "bank_authorisation",
          "required": true,
          "status": "pending"
        }
      ],
      "resources": {
        "customer": {
          "id": "CU123",
          "email": "alice@example.com",
          "given_name": "Alice",
          "family_name": "Smith",
          "company_name": null,
          "language": "en",
          "phone_number": null,
          "created_at": "2025-03-06T21:36:43Z"
        }
      },
      "links": {
        "customer": "CU123"
      }
    },
    "bank_authorisations": {
      "id": "BAU123",
      "created_at": "2025-03-06T21:36:43Z",
      "expires_at": "2025-03-06T21:51:43Z",
      "url": "https://pay.gocardless.com/obauth/BAU123",
      "qr_code_url": "https://pay.gocardless.com/obauth/BAU123/qr_code",
      "authorisation_type": "payment",
      "links": {
        "billing_request": "BRQ123"
      }
    }
  }
}

Request Body

billing_request_with_actionsobject

9 properties

mandate_requestobject

10 properties

currencystring

ISO 4217 currency code.

schemestring | null

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.

verifyenum

Verification preference for the mandate. One of:

minimum: only verify if absolutely required, such as when part of scheme rules
recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified
when_available: if verification mechanisms are available, use them
always: as when_available, but fail to create the Billing Request if a mechanism isn't available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

Possible values:minimumrecommendedwhen_availablealways

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

referencestring | null

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

descriptionstring | null

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

constraintsobject | null

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring | null

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring | null

The latest date at which payments can be taken, must occur after start_date if present

This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

A constraint where you can specify info (free text string) about how payments are calculated. For use when payments vary and cannot be expressed as a fixed amount and frequency. Note: This is only supported for ACH and PAD schemes.

periodic_limitsarray

Caps on the total amount and/or number of payments that can be collected within a repeating period (e.g. no more than a set amount per month), as opposed to max_amount_per_payment which caps a single payment.

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodenum

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

Possible values:dayweekmonthyearflexible

max_total_amountinteger | null

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger | null

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentenum

The alignment of the period. Defaults to creation_date if not specified.

calendar - the period follows fixed calendar boundaries, the same for every mandate: week runs Monday to Sunday, month runs from the 1st to the last day of the calendar month, and year runs from 1 January to 31 December. If the mandate starts partway through a period, the limit for that first period is reduced proportionally to the days remaining (e.g. a monthly limit starting on the 15th gives roughly half the limit for that first month).

creation_date - the period follows the mandate's own start date rather than the calendar. For example, if the mandate starts on the 15th, each monthly period runs from the 15th to the 14th of the following month. The first period is a full period, not reduced proportionally.

Note: Has no effect when period is flexible.

Possible values:calendarcreation_date

sweepingboolean

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

authorisation_sourceenum

This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

Possible values:webtelephonepaper

funds_settlementenum

This field will decide how GoCardless handles settlement of funds from the customer.

managed will be moved through GoCardless' account, batched, and payed out.
direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.

Possible values:manageddirect

payment_requestobject

9 properties

descriptionstring | null

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

currencystring

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

schemestring | null

(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in supported Eurozone countries (EUR). For Eurozone countries, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.

amountstring | integer

Amount in minor unit (e.g. pence in GBP, cents in EUR).

funds_settlementenum

This field will decide how GoCardless handles settlement of funds from the customer.

managed will be moved through GoCardless' account, batched, and payed out.
direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.

Possible values:manageddirect

app_feestring | integer

The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

referencestring | null

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

retry_if_possibleboolean

On failure, automatically retry payments using intelligent retries. Default is false.

Important

To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

Important

This is not applicable to Pay by Bank and VRP payments.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

linksobject

3 properties

customerstring

ID of the customer against which this request should be made.

customer_bank_accountstring

(Optional) ID of the customer_bank_account against which this request should be made.

creditorstring

ID of the associated creditor. Only required if your account manages multiple creditors.

fallback_enabledboolean

(Optional) If true, this billing request can fallback from instant payment to direct debit. Should not be set if GoCardless payment intelligence feature is used.

See Billing Requests: Retain customers with Fallbacks for more information.

purpose_codeenum

Specifies the high-level purpose/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

Possible values:mortgageutilityloandependant_supportgamblingretailsalarypersonalgovernmentpensiontaxotherbonus_paymentcash_management_transfercard_bulk_clearingcredit_card_paymenttrade_settlement_paymentdebit_card_paymentdividenddeliver_against_paymentepaymentfee_collection_and_interestfee_collectionperson_to_person_paymentgovernment_paymenthedging_transactionirrevocable_credit_card_paymentirrevocable_debit_card_paymentintra_company_paymentinterestlockbox_transactionscommercialconsumerother_paymentpension_paymentrepresentedreimbursement_received_credit_transferreceive_against_paymentsalary_paymentsecuritiessocial_security_benefitsupplier_paymenttax_paymenttradetreasury_paymentvalue_added_tax_paymentwith_holdingcash_management_sweep_accountcash_management_top_accountcash_management_zero_balance_accountcrossborder_mi_paymentsforeign_currency_domestic_transfercash_in_pre_creditcash_out_notes_coinscarrier_guarded_wholesale_valuables

payment_purpose_codestring

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

payment_context_codeenum

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

Possible values:billing_goods_and_services_in_advancebilling_goods_and_services_in_arrearsface_to_face_point_of_saleecommerce_merchant_initiated_paymenttransfer_to_selftransfer_to_third_party

actionsobject

Action payloads

6 properties

collect_customer_detailsobject

2 properties

customerobject

7 properties

emailstring | null

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring | null

Customer's first name. Required unless a company_name is provided.

family_namestring | null

Customer's surname. Required unless a company_name is provided.

company_namestring | null

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

languagestring | null

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided and a customer was linked during billing request creation, the linked customer language will be used. Otherwise, the language is default to "en".

phone_numberstring | null

ITU E.123 formatted phone number, including country code.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

customer_billing_detailobject

10 properties

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. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

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. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring | null

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

ip_addressstring | null

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

collect_bank_accountobject

11 properties

account_numberstring | null

Bank account number - see local details for more information. Alternatively you can provide an iban.

bank_codestring | null

Bank code - see local details for more information. Alternatively you can provide an iban.

branch_codestring | null

Branch code - see local details for more information. Alternatively you can provide an iban.

ibanstring | null

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring | null

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring | null

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_typeenum | null

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

Possible values:savingschecking

account_number_suffixstring | null

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

pay_idstring

A unique record such as an email address, mobile number or company number, that can be used to make and accept payments.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

select_institutionobject

2 properties

institutionstringrequired

The unique identifier for this institution

country_codestringrequired

ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.

confirm_payer_detailsobject

2 properties

payer_requested_dual_signatureboolean

This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

create_bank_authorisationboolean

Create a bank authorisation object as part of this request

bank_authorisation_redirect_uristring | null

URL for an oauth flow that will allow the user to authorise the payment

Response 201

Resource created successfully

billing_request_with_actionsobject

2 properties

billing_requestsobjectrequired

See Billing Requests: Overview for how-to's, explanations and tutorials.

Important

All properties associated with subscription_request and instalment_schedule_request are only supported for ACH and PAD schemes.

16 properties

idstringrequired

Unique identifier, beginning with "BRQ".

purpose_codeenum

payment_purpose_codestring

payment_context_codeenum

Possible values:billing_goods_and_services_in_advancebilling_goods_and_services_in_arrearsface_to_face_point_of_saleecommerce_merchant_initiated_paymenttransfer_to_selftransfer_to_third_party

created_atstring

Fixed timestamp, recording when this resource was created.

statusenum

One of:

pending: the billing request is pending and can be used
ready_to_fulfil: the billing request is ready to fulfil
fulfilling: the billing request is currently undergoing fulfilment
fulfilled: the billing request has been fulfilled and a payment created
cancelled: the billing request has been cancelled and cannot be used

Possible values:pendingready_to_fulfilfulfillingfulfilledcancelled

metadataobject | null

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

mandate_requestobject | null

Request for a mandate

12 properties

descriptionobject

currencyobject

schemeobject

sweepingobject

verifyobject

linksobject

metadataobject

consent_typeobject

constraintsobject

payer_requested_dual_signatureobject

authorisation_sourceobject

funds_settlementobject

payment_requestobject | null

Request for a one-off strongly authorised payment

10 properties

descriptionobject

currencyobject

schemeobject

amountobject

linksobject

app_feeobject

metadataobject

referenceobject

funds_settlementobject

retry_if_possibleobject

subscription_requestobject | null

Request for a subscription

14 properties

amountobject

currencyobject

interval_unitobject

intervalobject

app_feeobject

countobject

day_of_monthobject

metadataobject

linksobject

monthobject

nameobject

payment_referenceobject

start_dateobject

retry_if_possibleobject

instalment_schedule_requestobject | null

Request for an instalment schedule. Has to contain either instalments_with_schedule object or an array of instalments_with_dates objects

10 properties

nameobject

currencyobject

total_amountobject

payment_referenceobject

app_feeobject

instalments_with_datesobject

instalments_with_scheduleobject

metadataobject

linksobject

retry_if_possibleobject

actionsarray

List of actions that can be performed before this billing request can be fulfilled.

10 properties

typeobject

statusobject

requiredobject

completes_actionsobject

requires_actionsobject

bank_authorisationobject

collect_customer_detailsobject

available_currenciesobject

available_country_codesobject

institution_guess_statusobject

resourcesobject

3 properties

customerobject

Embedded customer

9 properties

idobject

created_atobject

emailobject

given_nameobject

family_nameobject

company_nameobject

languageobject

phone_numberobject

metadataobject

customer_billing_detailobject

Embedded customer billing detail

13 properties

idobject

schemesobject

created_atobject

address_line1object

address_line2object

address_line3object

cityobject

regionobject

postal_codeobject

country_codeobject

swedish_identity_numberobject

danish_identity_numberobject

ip_addressobject

customer_bank_accountobject | null

Embedded customer bank account, only if a bank account is linked

13 properties

idobject

created_atobject

account_holder_nameobject

account_number_endingobject

account_typeobject

country_codeobject

currencyobject

bank_nameobject

enabledobject

metadataobject

linksobject

bank_account_tokenobject

payer_name_verification_resultobject

linksobject

15 properties

customerstring

ID of the customer that will be used for this request

customer_billing_detailstring

ID of the customer billing detail that will be used for this request

creditorstring

ID of the associated creditor.

organisationstring

ID of the associated organisation.

customer_bank_accountstring

(Optional) ID of the customer_bank_account that will be used for this request

bank_authorisationstring

(Optional) ID of the bank authorisation that was used to verify this request.

payment_requeststring

(Optional) ID of the associated payment request

payment_request_paymentstring

(Optional) ID of the payment that was created from this payment request.

mandate_requeststring

(Optional) ID of the associated mandate request

mandate_request_mandatestring

(Optional) ID of the mandate that was created from this mandate request. this mandate request.

subscription_requeststring

(Optional) ID of the associated subscription request

subscription_request_subscriptionstring

(Optional) ID of the subscription that was created from this subscription request.

instalment_schedule_requeststring

(Optional) ID of the associated instalment schedule request

instalment_schedule_request_instalment_schedulestring

(Optional) ID of the instalment_schedule that was created from this instalment schedule request.

payment_providerstring

(Optional) ID of the associated payment provider

fallback_enabledboolean

(Optional) If true, this billing request can fallback from instant payment to direct debit. Should not be set if GoCardless payment intelligence feature is used.

See Billing Requests: Retain customers with Fallbacks for more information.

fallback_occurredboolean

True if the billing request was completed with direct debit.

bank_authorisationsobject | null

Bank authorisation resource, or null if no bank authorisation was created.

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

Was this helpful?

Support Dashboard