GoCardlessDeveloper Docs
Create a sandbox account

Bank Account Holder Verification

View as Markdown

Create a bank account holder verification for a bank account.

Create a bank account holder verification.#

POST/bank_account_holder_verifications

Verify the account holder of the bank account. A complete verification can be attached when creating an outbound payment. This endpoint allows partner merchants to create Confirmation of Payee checks on customer bank accounts before sending outbound payments.

POST https://api.gocardless.com/bank_account_holder_verifications HTTP/1.1
Content-Type: application/json
{
  "bank_account_holder_verifications": {
    "type": "confirmation_of_payee",
    "links": {
      "bank_account": "BA123"
    }
  }
}
@client.bank_account_holder_verifications.create(
  params: {
    type: "confirmation_of_payee",
    links: {
      bank_account: "BA123"
    }
  }
)
client.bank_account_holder_verifications.create(params={
  "type": "confirmation_of_payee",
  "links": {
    "bank_account": "BA123"
  }
})
const verification = await client.bankAccountHolderVerifications.create({
  type: "confirmation_of_payee",
  links: {
    bank_account: "BA123"
  }
});
$client->bankAccountHolderVerifications()->create([
  "params" => [
    "type" => "confirmation_of_payee",
    "links" => [
      "bank_account" => "BA123"
    ]
  ]
]);
import com.gocardless.services.BankAccountHolderVerificationService.BankAccountHolderVerificationCreateRequest.Type;

client.bankAccountHolderVerifications().create()
  .withType(Type.CONFIRMATION_OF_PAYEE)
  .withLinksBankAccount("BA123")
  .execute();
bankAccountHolderVerificationCreateParams := gocardless.BankAccountHolderVerificationCreateParams{
  Type: "confirmation_of_payee",
  Links: gocardless.BankAccountHolderVerificationCreateParamsLinks{
    BankAccount: "BA123",
  },
}

verification, err := client.BankAccountHolderVerifications.Create(ctx, bankAccountHolderVerificationCreateParams)
var verificationLinks = new GoCardless.Services.BankAccountHolderVerificationCreateRequest.BankAccountHolderVerificationLinks
{
  BankAccount = "BA123"
};

var resp = await client.BankAccountHolderVerifications.CreateAsync(
  new GoCardless.Services.BankAccountHolderVerificationCreateRequest()
  {
    Type = GoCardless.Services.BankAccountHolderVerificationCreateRequest.BankAccountHolderVerificationType.ConfirmationOfPayee,
    Links = verificationLinks,
  }
);
Responsehttp
HTTP/1.1 201 Created
Content-Type: application/json
{
  "bank_account_holder_verifications": {
    "id": "BAHV123",
    "type": "confirmation_of_payee",
    "result": "partial_match",
    "status": "pending"
  }
}
Request Body
bank_account_holder_verificationsobject
3 properties
typestringrequired

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee
referencestring | null

An alphanumeric reference code used by some financial institutions to identify an individual account.

linksobjectrequired
1 properties
bank_accountstringrequired

The ID of the bank account to verify, e.g. "BA123".

Response 201

Resource created successfully

bank_account_holder_verificationsobject
5 properties
idstringrequired

The unique identifier for the bank account holder verification resource, e.g. "BAHV123".

typestringrequired

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee
resultstring

Result of the verification, could be one of

  • full_match: The verification has confirmed that the account name exactly matches the details provided.
  • partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
  • no_match: The verification concludes the provided name does not match the account details.
  • unable_to_match: The verification could not be performed due to recipient bank issues or technical issues
full_matchpartial_matchno_matchunable_to_match
actual_account_namestring | null

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

statusstringrequired

The status of the bank account holder verification.

  • pending: We have triggered the verification, but the result has not come back yet.
  • completed: The verification is complete and is ready to be used.
pendingcompleted
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

Get a bank account holder verification.#

GET/bank_account_holder_verifications/{bank_account_holder_verification_id}

Fetches a bank account holder verification by ID.

Path Parameters

NameTypeDescription
bank_account_holder_verification_idstringrequired

The bank account holder verification id

GET https://api.gocardless.com/bank_account_holder_verifications/BAHV123
@client.bank_account_holder_verifications.get("BAHV123")
client.bank_account_holder_verifications.get("BAHV123")
const resp = await client.bankAccountHolderVerifications.find("BAHV123");
$client->bankAccountHolderVerifications()->get("BAHV123");
client.bankAccountHolderVerifications().get("BAHV123").execute();
verification, err := client.BankAccountHolderVerifications.Get(ctx, "BAHV123")
var resp = await client.BankAccountHolderVerifications.GetAsync("BAHV123");
Responsehttp
HTTP/1.1 200
Content-Type: application/json
{
  "bank_account_holder_verifications": {
    "id": "BAHV123",
    "type": "confirmation_of_payee",
    "result": "partial_match",
    "status": "pending",
    "actual_account_name": null
  }
}

GET https://api.gocardless.com/bank_account_holder_verifications/BAHV124

HTTP/1.1 200
Content-Type: application/json
{
  "bank_account_holder_verifications": {
    "id": "BAHV123",
    "type": "confirmation_of_payee",
    "result": "partial_match",
    "status": "completed",
    "actual_account_name": "Test Recipient"
  }
}
Response 200

Successful response

bank_account_holder_verificationsobject
5 properties
idstringrequired

The unique identifier for the bank account holder verification resource, e.g. "BAHV123".

typestringrequired

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee
resultstring

Result of the verification, could be one of

  • full_match: The verification has confirmed that the account name exactly matches the details provided.
  • partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
  • no_match: The verification concludes the provided name does not match the account details.
  • unable_to_match: The verification could not be performed due to recipient bank issues or technical issues
full_matchpartial_matchno_matchunable_to_match
actual_account_namestring | null

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

statusstringrequired

The status of the bank account holder verification.

  • pending: We have triggered the verification, but the result has not come back yet.
  • completed: The verification is complete and is ready to be used.
pendingcompleted
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