GoCardlessDeveloper Docs
Create a sandbox account

Billing Request

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#

POST/billing_requests

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

POST https://api.gocardless.com/billing_requests HTTP/1.1
Content-Type: application/json
{
  "billing_requests": {
    "payment_request": {
      "description": "First Payment",
      "amount": "500",
      "currency": "GBP"
    },
    "mandate_request": {
      "scheme": "bacs"
    }
  }
}
@client.billing_requests.create(
  params: {
    payment_request: {
      description: "First Payment",
      amount: "500",
      currency: "GBP",
    },
    mandate_request: {
      scheme: "bacs"
    }
  }
)
client.billing_requests.create(params={
  "payment_request": {
    "description": "First Payment",
    "amount": "500",
    "currency": "GBP",
  },
  "mandate_request": {
    "scheme": "bacs"
  }
})
const billingRequest = await client.billingRequests.create({
  payment_request: {
    description: "First Payment",
    amount: "500",
    currency: "GBP",
  },
  mandate_request: {
    scheme: "bacs"
  }
});
$client->billingRequests()->create([
  "params" => [
    "payment_request" => [
      "description" => "First Payment",
      "amount" => "500",
      "currency" => "GBP",
    ],
    "mandate_request" => [
      "scheme" => "bacs"
    ]
  ]
]);
BillingRequest billingRequest = client.billingRequests().create()
  .withPaymentRequestDescription("First Payment")
  .withPaymentRequestAmount(500)
  .withPaymentRequestCurrency("GBP")
  .withMandateRequestScheme("bacs")
  .execute();
billingRequestCreateParams := gocardless.BillingRequestCreateParams{
  PaymentRequest: &gocardless.BillingRequestCreateParamsPaymentRequest{
    Amount:      1000,
    Currency:    "GBP",
    Description: "First Payment",
  },
  MandateRequest: &gocardless.BillingRequestCreateParamsMandateRequest{
    Scheme: "bacs",
  },
}

billingRequest, err := client.BillingRequests.Create(ctx, billingRequestCreateParams)
var paymentRequest = new GoCardless.Services.BillingRequestCreateRequest.BillingRequestPaymentRequest
{
  Description = "First payment",
  Amount = 500,
  Currency = "GBP",
};

var mandateRequest = new GoCardless.Services.BillingRequestCreateRequest.BillingRequestMandateRequest
{
  Scheme = "bacs",
};

var resp = await client.BillingRequests.CreateAsync(
  new GoCardless.Services.BillingRequestCreateRequest()
  {
    PaymentRequest = paymentRequest,
    MandateRequest = mandateRequest,
  }
);

GoCardless.Resources.BillingRequest billingRequest = resp.BillingRequest;
Responsehttp
HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": null,
                "family_name": null,
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": null,
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Request Body
billing_requestsobject
10 properties
mandate_requestobject
11 properties
currencystring

ISO 4217 currency code.

schemestring

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.

verifystring

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.

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

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

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

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

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_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

payment_requestobject
9 properties
descriptionstring

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

(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.

amountobject

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

funds_settlementstring

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.
manageddirect
app_feeobject

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

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.

subscription_requestobject
13 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

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

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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.

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject
9 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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.

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.

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_codestring

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.

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_codestring

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.

billing_goods_and_services_in_advancebilling_goods_and_services_in_arrearsface_to_face_point_of_saleecommerce_merchant_initiated_paymenttransfer_to_selftransfer_to_third_party
Response 201

Resource created successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

List Billing Requests#

GET/billing_requests

Returns a cursor-paginated list of your billing requests.

GET https://api.gocardless.com/billing_requests HTTP/1.1
@client.billing_requests.list
client.billing_requests.list().records
const billingRequests = await client.billingRequests.list();
$client->billingRequests()->list();
for (BillingRequest billingRequest : client.billingRequests().all().execute()) {
  System.out.println(billingRequest.getId());
}
billingRequestListParams := gocardless.BillingRequestListParams{}
billingRequestListResult, err :=  client.BillingRequests.List(ctx, billingRequestListParams)
for _, billingRequest := range billingRequestListResult.BillingRequests {
    fmt.Println(billingRequest.Id)
}
var billingRequestListResponse = client.BillingRequests.All();
foreach (GoCardless.Resources.BillingRequest billingRequest in billingRequestListResponse)
{
    Console.WriteLine(billingRequest.Id);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "billing_requests": [
    {
       "id": "BRQ123",
       "created_at": "2021-03-22T16:23:48.486Z",
       "status": "pending",
       "mandate_request": null,
       "payment_request": {
           "description": "£5 Top Up",
           "currency": "GBP",
           "amount": 500,
           "scheme": "faster_payments",
           "links": {}
       },
       "metadata": {},
       "links": {
           "customer": "CU123",
           "customer_billing_detail": "CBD123",
           "customer_bank_account": "BA123"
       }
     }
   ]
}
Response 200

Successful response

billing_requestsarray
9 properties
idstring

Unique identifier, beginning with "BRQ".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

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

metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Collect customer details#

POST/billing_requests/{billing_request_id}/actions/collect_customer_details

If the billing request has a pending collect_customer_details action, this endpoint can be used to collect the details in order to complete it.

The endpoint takes the same payload as Customers, but checks that the customer fields are populated correctly for the billing request scheme.

Whatever is provided to this endpoint is used to update the referenced customer, and will take effect immediately after the request is successful.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_customer_details HTTP/1.1
Content-Type: application/json
{
  "data": {
    "customer": {
      "email": "alice@example.com",
      "given_name": "Alice",
      "family_name": "Smith"
    },
    "customer_billing_detail": {
      "address_line1": "1 Somewhere Lane"
    }
  }
}
@client.billing_requests.collect_customer_details("BR123", {
  params: {
    customer: {
      email: "alice@example.com",
      given_name: "Alice",
      family_name: "Smith",
    },
    customer_billing_detail: {
      address_line1: "1 Somewhere Lane"
    }
  }
})
client.billing_requests.collect_customer_details("BR123", params={
  "customer": {
    "email": "alice@example.com",
    "given_name": "Alice",
    "family_name": "Smith"
  },
  "customer_billing_detail": {
    "address_line1": "1 Somewhere Lane"
  }
})
const resp = await client.billingRequests.collectCustomerDetails("BR123", {
  customer: {
    email: "alice@example.com",
    given_name: "Alice",
    family_name: "Smith",
  },
  customer_billing_detail: {
    address_line1: "1 Somewhere Lane"
  }
});
$client->billingRequests()->collectCustomerDetails("BR123", [
  "params" => [
    "customer" => [
      "email" => "alice@example.com",
      "given_name" => "Alice",
      "family_name" => "Smith"
    ],
    "customer_billing_detail" => [
      "address_line1" => "1 Somewhere Lane"
    ]
  ]
]);
client.billingRequests().collectCustomerDetails("BR123")
  .withCustomerEmail("alice@example.com")
  .withCustomerGivenName("Alice")
  .withCustomerFamilyName("Smith")
  .withCustomerBillingDetailAddressLine1("1 Somewhere Lane")
  .execute();
billingRequestCollectCustomerDetailsParams := gocardless.BillingRequestCollectCustomerDetailsParams{
  Customer: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomer{
    GivenName:  "Alice",
    FamilyName: "Smith",
    Email:      "alice@example.com",
  },
  CustomerBillingDetail: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomerBillingDetail{
    AddressLine1: "1 Somewhere Lane",
  },
}

billingRequest, err := client.BillingRequests.CollectCustomerDetails(ctx, "BR123", billingRequestCollectCustomerDetailsParams)
var customer = new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest.BillingRequestCustomer
{
  Email = "alice@example.com",
  GivenName = "Alice",
  FamilyName = "Smith",
};

var customerBillingDetail = new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest.BillingRequestCustomerBillingDetail
{
  AddressLine1 = "1 Somewhere Lane",
};

var resp = await client.BillingRequests.CollectCustomerDetailsAsync("BR123",
  new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest
  {
    Customer = customer,
    CustomerBillingDetail = customerBillingDetail,
  });
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "creditor": "CR123",
            "mandate_request": "MRQ123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": "alice@example.com",
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            }
        }
    }
}
Request Body
billing_requestsobject
2 properties
customerobject
7 properties
emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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

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

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

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. 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

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

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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Collect bank account details#

POST/billing_requests/{billing_request_id}/actions/collect_bank_account

If the billing request has a pending collect_bank_account action, this endpoint can be used to collect the details in order to complete it.

The endpoint takes the same payload as Customer Bank Accounts, but check the bank account is valid for the billing request scheme before creating and attaching it.

If the scheme is PayTo and the pay_id is available, this can be included in the payload along with the country_code.

ACH scheme For compliance reasons, an extra validation step is done using a third-party provider to make sure the customer's bank account can accept Direct Debit. If a bank account is discovered to be closed or invalid, the customer is requested to adjust the account number/routing number and succeed in this check to continue with the flow.

BACS scheme Payer Name Verification is enabled by default for UK based bank accounts, meaning we verify the account holder name and bank account number match the details held by the relevant bank.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_bank_account HTTP/1.1
Content-Type: application/json
{
  "data": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB"
  }
}
@client.billing_requests.collect_bank_account("BR123", {
  params: {
    account_number: "55779911",
    branch_code: "200000",
    account_holder_name: "Frank Osborne",
    country_code: "GB",
  }
})
client.billing_requests.collect_bank_account("BR123", params={
  "account_number": "55779911",
  "branch_code": "200000",
  "account_holder_name": "Frank Osborne",
  "country_code": "GB"
})
const resp = await client.billingRequests.collectBankAccount("BR123", {
  account_number: "55779911",
  branch_code: "200000",
  account_holder_name: "Frank Osborne",
  country_code: "GB",
});
$client->billingRequests()->collectBankAccount("BR123", [
  "params" => [
    "account_number" => "55779911",
    "branch_code" => "200000",
    "account_holder_name" => "Frank Osborne",
    "country_code" => "GB"
  ]
]);
client.billingRequests().collectBankAccount("BR123")
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withAccountHolderName("Frank Osborne")
  .withCountryCode("GB")
  .execute();
billingRequestCollectBankAccountParams := gocardless.BillingRequestCollectBankAccountParams{
  BranchCode:        "200000",
  CountryCode:       "GB",
  AccountNumber:     "55779911",
  AccountHolderName: "Frank Osborne",
}

billingRequest, err := client.BillingRequests.CollectBankAccount(ctx, "BR123", billingRequestCollectBankAccountParams)
var resp = await client.BillingRequests.CollectBankAccountAsync("BR123",
  new GoCardless.Services.BillingRequestCollectBankAccountRequest
  {
    AccountNumber = "55779911",
    BranchCode = "200000",
    AccountHolderName = "Frank Osborne",
    CountryCode = "GB",
  });
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
          "customer": "CU123",
          "customer_bank_account": "BA123",
          "creditor": "CR123",
          "mandate_request": "MRQ123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_bank_account": {
                "id": "BA123",
                "created_at": "2014-05-08T17:01:06.000Z",
                "account_holder_name": "Frank Osborne",
                "account_number_ending": "11",
                "country_code": "GB",
                "currency": "GBP",
                "bank_name": "BARCLAYS BANK PLC",
                "metadata": {},
                "enabled": true,
                "links": {
                  "customer": "CU123"
                }
            }
        }
    }
}
Request Body
billing_requestsobject
11 properties
account_numberstring

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

bank_codestring

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

branch_codestring

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

ibanstring

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

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

currencystring

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_typestring

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.

savingschecking
account_number_suffixstring

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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Confirm the payer details#

POST/billing_requests/{billing_request_id}/actions/confirm_payer_details

This is needed when you have a mandate request. As a scheme compliance rule we are required to allow the payer to crosscheck the details entered by them and confirm it.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/confirm_payer_details HTTP/1.1
@client.billing_requests.confirm_payer_details("BR123")
client.billing_requests.confirm_payer_details("BR123")
const resp = await client.billingRequests.confirmPayerDetails("BR123");
$client->billingRequests()->confirmPayerDetails("BR123");
client.billingRequests().confirmPayerDetails("BR123").execute();
BillingRequestConfirmPayerDetailsParams := gocardless.BillingRequestConfirmPayerDetailsParams{}
billingRequest, err := client.BillingRequests.ConfirmPayerDetails(ctx, "BR123", BillingRequestConfirmPayerDetailsParams)
var resp = await client.BillingRequests.ConfirmPayerDetailsAsync("BR123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "ready_to_fulfil",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": null,
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_bank_account": "BA123",
            "creditor": "CR123",
            "mandate_request": "MRQ123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "confirm_payer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_customer_details",
                    "collect_bank_account"
                ],
                "status": "completed"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_bank_account": {
                "id": "BA123",
                "created_at": "2022-11-01T16:30:37.969Z",
                "account_number_ending": "11",
                "account_holder_name": "HOME LOAN ACCOUNT",
                "account_type": null,
                "bank_name": "BARCLAYS BANK PLC",
                "currency": "GBP",
                "country_code": "GB",
                "metadata": {},
                "enabled": true,
                "links": {
                    "customer": "CU123"
                }
            }
        }
    }
}
Request Body
billing_requestsobject
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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Fulfil a Billing Request#

POST/billing_requests/{billing_request_id}/actions/fulfil

If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/fulfil HTTP/1.1
@client.billing_requests.fulfil("BR123")
client.billing_requests.fulfil("BR123")
const resp = await client.billingRequests.fulfil("BR123");
$client->billingRequests()->fulfil("BR123");
client.billingRequests().fulfil("BR123").execute();
billingRequestFulfilParams := gocardless.BillingRequestFulfilParams{}
billingRequest, err := client.BillingRequests.Fulfil(ctx, "BR123", billingRequestFulfilParams)
var resp = await client.BillingRequests.FulfilAsync("BR123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "fulfilled",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {
              "mandate": "MD123"
            }
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {
              "payment": "PM123"
            }
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Request Body
billing_requestsobject
1 properties
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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Cancel a Billing Request#

POST/billing_requests/{billing_request_id}/actions/cancel

Immediately cancels a billing request, causing all billing request flows to expire.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/cancel HTTP/1.1
@client.billing_requests.cancel("BR123")
client.billing_requests.cancel("BR123")
const resp = await client.billingRequests.cancel("BR123");
$client->billingRequests()->cancel("BR123");
client.billingRequests().cancel("BR123").execute();
billingRequestCancelParams := gocardless.BillingRequestCancelParams{}
billingRequest, err := client.BillingRequests.Cancel(ctx, "BR123", billingRequestCancelParams)
var resp = await client.BillingRequests.CancelAsync("BR123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "cancelled",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Request Body
billing_requestsobject
1 properties
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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single Billing Request#

GET/billing_requests/{billing_request_id}

Fetches a billing request

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

GET https://api.gocardless.com/billing_requests/BRQ123 HTTP/1.1
@client.billing_requests.get("BR123")
client.billing_requests.get("BR123")
const resp = await client.billingRequests.find("BR123");
$client->billingRequests()->get("BR123");
client.billingRequests().get("BR123").execute();
billingRequest, err := client.BillingRequests.Get(ctx, "BR123")
var resp = await client.BillingRequests.GetAsync("BR123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": null,
                "family_name": null,
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": null,
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Response 200

Successful response

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Notify the customer#

POST/billing_requests/{billing_request_id}/actions/notify

Notifies the customer linked to the billing request, asking them to authorise it. Currently, the customer can only be notified by email.

This endpoint is currently supported only for Pay by Bank Billing Requests.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/notify HTTP/1.1
Content-Type: application/json
{
  "data": {
    "notification_type": "email",
    "redirect_uri": "https://my-company.com"
  }
}
@client.billing_requests.notify("BR123", {
  params: {
    notification_type: "email",
    redirect_uri: "https://my-company.com",
  }
})
client.billing_requests.notify("BR123", params={
  "notification_type": "email",
  "redirect_uri": "https://my-company.com"
})
const resp = await client.billingRequests.notify("BR123", {
  notification_type: "email",
  redirect_uri: "https://my-company.com",
});
$client->billingRequests()->notify("BR123", [
  "params" => [
    "notification_type" => "email",
    "redirect_uri" => "https://my-company.com"
  ]
]);
client.billingRequests().notify("BR123")
  .withNotificationType("email")
  .withRedirectUri("https://my-company.com")
  .execute();
billingRequestNotifyParams := gocardless.BillingRequestNotifyParams{
  NotificationType: "email",
  RedirectUri:      "https://my-company.com",
}

billingRequest, err := client.BillingRequests.Notify(ctx, "BR123", billingRequestNotifyParams)
var resp = await client.BillingRequests.NotifyAsync("BR123",
  new GoCardless.Services.BillingRequestNotifyRequest
  {
    NotificationType = "email",
    RedirectUri = "https://my-company.com",
  });
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "pending"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Request Body
billing_requestsobject
2 properties
notification_typestring

Currently, can only be email.

email
redirect_uristring

URL that the payer can be redirected to after authorising the payment.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Trigger fallback#

POST/billing_requests/{billing_request_id}/actions/fallback

Triggers a fallback from the open-banking flow to direct debit. Note, the billing request must have fallback enabled.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/fallback HTTP/1.1
@client.billing_requests.fallback("BR123")
client.billing_requests.fallback("BR123")
const resp = await client.billingRequests.fallback("BR123");
$client->billingRequests()->fallback("BR123");
client.billingRequests().fallback("BR123").execute();
billingRequest, err := client.BillingRequests.Fallback(ctx, "BR123", gocardless.BillingRequestFallbackParams{})
var resp = await client.BillingRequests.FallbackAsync("BR123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "bacs",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "address_line1": null,
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
      },
      "fallback_enabled": true,
      "fallback_occurred": true
  }
}
Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Change currency#

POST/billing_requests/{billing_request_id}/actions/choose_currency

This will allow for the updating of the currency and subsequently the scheme if needed for a Billing Request. This will only be available for mandate only flows which do not have the lock_currency flag set to true on the Billing Request Flow. It will also not support any request which has a payments request.

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/choose_currency HTTP/1.1
Content-Type: application/json
{
  "data": {
    "currency": "GBP"
  }
}
@client.billing_requests.choose_currency("BR123", {
  params: {
    currency: "GBP"
  }
})
client.billing_requests.choose_currency("BR123", params={
  "currency": "GBP"
})
const resp = await client.billingRequests.chooseCurrency("BR123", {
  currency: "GBP"
});
$client->billingRequests()->chooseCurrency("BR123", [
  "params" => [
    "currency" => "GBP"
  ]
]);
client.billingRequests().chooseCurrency("BR123")
  .withCurrency("GBP")
  .execute();
billingRequestChooseCurrencyParams := gocardless.BillingRequestChooseCurrencyParams{
  Currency: "GBP",
}

billingRequest, err := client.BillingRequests.ChooseCurrency(ctx, "BR123", billingRequestChooseCurrencyParams)
var resp = await client.BillingRequests.ChooseCurrencyAsync("BR123",
  new GoCardless.Services.BillingRequestChooseCurrencyRequest
  {
    Currency = "GBP",
  });
Request Body
billing_requestsobject
2 properties
currencystring

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

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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Select institution for a Billing Request#

POST/billing_requests/{billing_request_id}/actions/select_institution

Creates an Institution object and attaches it to the Billing Request

Path Parameters

NameTypeDescription
billing_request_idrequiredstring

The billing request id

POST https://api.gocardless.com/billing_requests/BRQ123/actions/select_institution HTTP/1.1
Content-Type: application/json
{
  "data": {
    "institution": "monzo",
    "country_code": "GB"
  }
}
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2021-03-22T12:20:04.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
        "payment_request": {
            "description": "First Payment",
            "currency": "GBP",
            "amount": 500,
            "scheme": "faster_payments",
            "links": {}
        },
        "metadata": {},
        "links": {
            "customer": "CU123",
            "customer_billing_detail": "CBD123"
        },
        "actions": [
            {
                "type": "choose_currency",
                "required": true,
                "completes_actions": [],
                "requires_actions": [],
                "status": "completed"
            },
            {
                "type": "collect_customer_details",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "choose_currency"
                ],
                "status": "pending",
                "collect_customer_details": {
                    "incomplete_fields": {
                        "customer": [
                            "email",
                            "given_name",
                            "family_name"
                        ],
                        "customer_billing_detail": [
                            "address_line1",
                            "city",
                            "postal_code",
                            "country_code"
                        ]
                    }
                }
            },
            {
              "type": "select_institution",
              "required": false,
              "completes_actions": [],
              "requires_actions": [],
              "status": "completed"
            },
            {
                "type": "collect_bank_account",
                "required": true,
                "completes_actions": [
                    "choose_currency"
                ],
                "requires_actions": [],
                "status": "pending"
            },
            {
                "type": "bank_authorisation",
                "required": true,
                "completes_actions": [],
                "requires_actions": [
                    "collect_bank_account"
                ],
                "status": "pending"
            }
        ],
        "resources": {
            "customer": {
                "id": "CU123",
                "created_at": "2021-03-22T12:20:04.238Z",
                "email": null,
                "given_name": "Alice",
                "family_name": "Smith",
                "company_name": null,
                "language": "en",
                "phone_number": null,
                "metadata": {}
            },
            "customer_billing_detail": {
                "id": "CBD123",
                "created_at": "2021-03-22T12:20:04.374Z",
                "address_line1": "1 Somewhere Lane",
                "address_line2": null,
                "address_line3": null,
                "city": null,
                "region": null,
                "postal_code": null,
                "country_code": null,
                "swedish_identity_number": null,
                "danish_identity_number": null
            }
        }
    }
}
Request Body
billing_requestsobject
2 properties
institutionstring

The unique identifier for this institution

country_codestring

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.

Response 200

Action completed successfully

billing_requestsobject
16 properties
idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

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.

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_codestring

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.

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.

statusstring

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
pendingready_to_fulfilfulfillingfulfilledcancelled
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.

mandate_requestobject

Request for a mandate

12 properties
descriptionstring

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.

schemestring

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.

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

verifystring

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.

minimumrecommendedwhen_availablealways
linksobject
1 properties
mandatestring

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

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

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

5 properties
start_datestring

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

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
periodstring

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.

dayweekmonthyearflexible
max_total_amountinteger

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

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

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

alignmentstring

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.

calendarcreation_date
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.

authorisation_sourcestring

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)

webtelephonepaper
funds_settlementstring

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.
manageddirect
payment_requestobject

Request for a one-off strongly authorised payment

9 properties
descriptionstring

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

(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.

amountobject

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

linksobject
1 properties
paymentstring

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

app_feeobject

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

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.

funds_settlementstring

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.
manageddirect
subscription_requestobject

Request for a subscription

14 properties
amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

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

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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
1 properties
subscriptionstring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember
namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

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.

instalment_schedule_requestobject

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

10 properties
namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

app_feeobject

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

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties
amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties
start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly
amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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
1 properties
instalment_schedulestring

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

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.

actionsarray

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

9 properties
typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution
statusstring

Status of the action

pendingcompleted
requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties
adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring
authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate
collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties
default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject
2 properties
customerarray
customer_billing_detailarray
available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

  • not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
  • pending: we are waiting on the bank details in order to infer the institution
  • failed: we weren't able to infer the institution
  • success: we inferred the institution and added it to the resources of a Billing Request
not_neededpendingfailedsuccess
resourcesobject
3 properties
customerobject

Embedded customer

9 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

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

given_namestring

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

family_namestring

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

company_namestring

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

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, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

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

Embedded customer billing detail

13 properties
idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

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

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. 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

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

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.

customer_bank_accountobject

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

13 properties
idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

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_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

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.

savingschecking
country_codestring

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

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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
1 properties
customerstring

ID of the customer that owns this bank account.

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

  • full: The name provided matches the name held by the bank.
  • close: The name provided is a close but not exact match to the name held by the bank.
  • cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.
fullclosecannot_perform_verification
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.

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
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard