# Billing Request Source: https://docs.gocardless.com/docs/api-reference/billing-request ## 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.

### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `mandate_request` | object | No | | | `payment_request` | object | No | | | `subscription_request` | object | No | | | `instalment_schedule_request` | object | No | | | `metadata` | object | No | 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. | | `links` | object | No | | | `fallback_enabled` | boolean | No | (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](https://developer.gocardless.com/billing-requests/retain-customers-with-fallbacks/) for more information. | | `purpose_code` | string | No | 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](https://developer.gocardless.com/billing-request-purpose-codes/) for the complete list of valid codes. | | `payment_purpose_code` | string | No | 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](https://developer.gocardless.com/vrp-commercial-payment-purpose-codes/) for the complete list of valid codes. | | `payment_context_code` | string | No | 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. | ### Responses | Status | Description | | --- | --- | | 201 | Resource created successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## List Billing Requests `GET /billing_requests` Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your billing requests. ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `customer` | object | No | | | `customer_billing_detail` | object | No | | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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](https://hub.gocardless.com/s/article/Introduction-to-Payer-Name-Verification?language=en_GB) 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `account_number` | string | No | Bank account number - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `bank_code` | string | No | Bank code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `branch_code` | string | No | Branch code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`. | | `iban` | string | No | International Bank Account Number. Alternatively you can provide [local details](#appendix-local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](#local-bank-details-sweden). | | `country_code` | string | No | [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. | | `currency` | string | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `account_holder_name` | string | No | 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](#javascript-flow-customer-bank-account-tokens). | | `account_type` | string | No | Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information. | | `account_number_suffix` | string | No | Account number suffix (only for bank accounts denominated in NZD) - see [local details](#local-bank-details-new-zealand) for more information. | | `pay_id` | string | No | A unique record such as an email address, mobile number or company number, that can be used to make and accept payments. | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `payer_requested_dual_signature` | boolean | No | 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. | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Cancel a Billing Request `POST /billing_requests/{billing_request_id}/actions/cancel` Immediately cancels a billing request, causing all billing request flows to expire. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Get a single Billing Request `GET /billing_requests/{billing_request_id}` Fetches a billing request ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `notification_type` | string | No | Currently, can only be `email`. | | `redirect_uri` | string | No | URL that the payer can be redirected to after authorising the payment. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `currency` | string | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## 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 ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `billing_request_id` | path | string | Yes | The billing request id | ### Request body Wrap request body attributes in a `billing_requests` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `institution` | string | No | The unique identifier for this institution | | `country_code` | string | No | [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error |