GoCardlessDeveloper Docs
Create a sandbox account

Bank Details Lookup

View as Markdown

Look up the name and reachability of a bank account.

Perform a bank details lookup#

POST/bank_details_lookups

Performs a bank details lookup. As part of the lookup, a modulus check and reachability check are performed.

For UK-based bank accounts, where an account holder name is provided (and an account number, a sort code or an iban are already present), we verify that the account holder name and bank account number match the details held by the relevant bank.

If your request returns an error or the available_debit_schemes attribute is an empty array, you will not be able to collect payments from the specified bank account. GoCardless may be able to collect payments from an account even if no bic is returned.

Bank account details may be supplied using local details or an IBAN.

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.

Note: Usage of this endpoint is monitored. If your organisation relies on GoCardless for modulus or reachability checking but not for payment collection, please get in touch.

POST https://api.gocardless.com/bank_details_lookups HTTP/1.1
Content-Type: application/json
{
  "bank_details_lookups": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB"
  }
}
@client.bank_details_lookups.create(
  params: {
    country_code: "GB",
    account_number: "55779911",
    branch_code: "200000"
  }
)
client.bank_details_lookups.create(params={
  "account_number": "55779911",
  "branch_code": "200000",
  "country_code": "GB"
})
const bankDetailsLookup = await client.bankDetailsLookups.create({
  account_number: "55779911",
  branch_code: "200000",
  country_code: "GB"
});
$client->bankDetailsLookups()->create([
  "params" => ["account_number" => "55779911",
               "branch_code" => "200000",
               "country_code" => "GB"]
]);
BankDetailsLookup bankDetailsLookup = client.bankDetailsLookups().create()
  .withAccountNumber("55779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .execute();
bankDetailsLookupCreateParams := gocardless.BankDetailsLookupCreateParams{
  AccountNumber: "55779911",
  BranchCode:    "200000",
  CountryCode:   "GB",
}

bankDetailsLookup, err := client.BankDetailsLookups.Create(ctx, bankDetailsLookupCreateParams)
var bankDetailsRequest = new GoCardless.Services.BankDetailsLookupCreateRequest()
{
    AccountNumber = "55779911",
    BranchCode = "200000",
    CountryCode = "GB"
};

var bankDetailsResponse = await client.BankDetailsLookups.CreateAsync(bankDetailsRequest);
GoCardless.Resources.BankDetailsLookup bankDetails = bankDetailsResponse.BankDetailsLookup;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "bank_details_lookups": {
    "available_debit_schemes": ["bacs"],
    "bank_name": "BARCLAYS BANK PLC",
    "bic": "BARCGB22XXX"
  }
}
Request Body
bank_details_lookupsobject
6 properties
ibanstring

International Bank Account Number. Alternatively you can provide local details.

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.

country_codestring

ISO 3166-1 alpha-2 code. Must be provided if specifying local details.

account_holder_namestring

The account holder name associated with the account number (if available). If provided and the country code is GB, a payer name verification will be performed.

Response 201

Resource created successfully

bank_details_lookupsobject
3 properties
bank_namestring

The name of the bank with which the account is held (if available).

bicstring

ISO 9362 SWIFT BIC of the bank with which the account is held.

Even if no BIC is returned for an account, GoCardless may still be able to collect payments from it - you should refer to the available_debit_schemes attribute to determine reachability.

available_debit_schemesarray

Array of schemes supported for this bank account. This will be an empty array if the bank account is not reachable by any schemes.

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