GOgocardless
Billing Request

Collect bank account details

If the billing request has a pending <code>collect_bank_account</code> 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 and SEPA schemes Payer Name Verification is enabled by default for UK and Eurozone based bank accounts, meaning we verify the account holder name and bank account number/IBAN match the details held by the relevant bank. If there is no match, the endpoint will return a 422 - validation error on account_holder_name: "Account holder name does not match bank account details provided". Testing instructions are here

post/billing_requests/{billing_request_id}/actions/collect_bank_account

Request

  • Base URL
    https://api.gocardless.com
  • Auth
    HTTP bearer

Path parameters

billing_request_idstring required

The billing request id

Headers

GoCardless-Versionstring required

Request body

Example request

{
  "billing_requests": {
    "account_number": "55779911",
    "branch_code": "20-00-00",
    "iban": "GB60BARC20000055779911",
    "country_code": "GB",
    "currency": "EUR",
    "account_holder_name": "Billie Jean",
    "account_type": "savings",
    "account_number_suffix": "00"
  }
}

Response

Action completed successfully

Example response

{
  "billing_requests": {
    "id": "BRQ123",
    "created_at": "2015-01-01T12:00:00.000Z",
    "status": "pending",
    "account_information_request": {
      "country_code": "GB"
    },
    "mandate_request": {
      "description": "Top-up Payment",
      "currency": "GBP",
      "scheme": "bacs"
    },
    "payment_request": {
      "description": "Top-up Payment",
      "currency": "GBP",
      "scheme": "faster_payments",
      "amount": 1000,
      "app_fee": 100,
      "reference": "some-custom-ref"
    },
    "subscription_request": {
      "amount": 1000,
      "currency": "USD",
      "interval_unit": "monthly",
      "interval": 1,
      "app_fee": 100,
      "count": 5,
      "day_of_month": 28,
      "month": "january",
      "name": "12 month subscription",
      "payment_reference": "GOLDPLAN",
      "start_date": "2014-10-21"
    },
    "instalment_schedule_request": {
      "name": "Invoice 4404",
      "currency": "USD",
      "total_amount": 1000,
      "payment_reference": "GOLDPLAN",
      "app_fee": 100,
      "instalments_with_dates": [
        {
          "amount": 250,
          "charge_date": "2020-11-03"
        }
      ],
      "instalments_with_schedule": {
        "start_date": "2014-10-21",
        "interval": 1,
        "interval_unit": "monthly",
        "amounts": [
          1000
        ]
      }
    },
    "actions": [
      {
        "type": "collect_bank_account",
        "status": "pending",
        "required": true,
        "completes_actions": [
          "collect_bank_account"
        ],
        "requires_actions": [
          "collect_bank_account"
        ],
        "available_currencies": [
          "GBP"
        ],
        "available_country_codes": [
          "GB"
        ],
        "institution_guess_status": "pending"
      }
    ],
    "resources": {
      "customer": {
        "id": "CU123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "email": "user@example.com",
        "given_name": "Frank",
        "family_name": "Osborne",
        "company_name": "Hamilton Trading Ltd.",
        "language": "en",
        "phone_number": "+64 4 817 9999"
      },
      "customer_billing_detail": {
        "id": "CU123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "address_line1": "221B Baker Street",
        "address_line2": "Marylebone",
        "address_line3": "City of Westminster",
        "city": "London",
        "region": "Greater London",
        "postal_code": "NW1 6XE",
        "country_code": "GB",
        "swedish_identity_number": "556564-5404",
        "danish_identity_number": "2205506218",
        "ip_address": "127.0.0.1"
      },
      "customer_bank_account": {
        "id": "BA123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "account_holder_name": "Billie Jean",
        "account_number_ending": "1234",
        "account_type": "savings",
        "country_code": "GB",
        "currency": "EUR",
        "bank_name": "BARCLAYS BANK PLC",
        "enabled": true,
        "bank_account_token": "bat_f975ab3c-ecee-47a1-9590-5bb1d56fa113",
        "payer_name_verification_result": "full"
      }
    },
    "links": {
      "customer": "CU123",
      "creditor": "CR123",
      "organisation": "OR123",
      "customer_bank_account": "BA123",
      "account_information_request": "AIR123",
      "payment_request": "PRQ123",
      "payment_request_payment": "PM123",
      "mandate_request": "MRQ123",
      "mandate_request_mandate": "MD123",
      "subscription_request": "SBR123",
      "subscription_request_subscription": "SB123",
      "instalment_schedule_request": "ISR123",
      "instalment_schedule_request_instalment_schedule": "IS123",
      "payment_provider": "PP123"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.