Bank Details Lookup

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 or Eurozone-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 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".

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.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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",
    "payer_name_verification_result": null
  }
}

Request Body

bank_details_lookupsobject

6 properties

ibanstring | null

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

account_numberstring | null

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

bank_codestring | null

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

branch_codestring | null

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

country_codestring | null

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

account_holder_namestring | null

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

4 properties

bank_namestring | nullrequired

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

bicstring | nullrequired

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_schemesarrayrequired

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

payer_name_verification_resultenum | nullrequired

The result of the payer name verification check performed during the lookup. null if no 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.
null: Verification was not triggered. Either PNV is not supported for the scheme, or PNV feature is disabled for your organisation.

Possible values:fullclosecannot_perform_verification

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

Was this helpful?

Support Dashboard