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
2 properties
typestring

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

confirmation_of_payee
linksobject
1 properties
bank_accountstring

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

Response 201

Resource created successfully

bank_account_holder_verificationsobject
5 properties
idstring

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

typestring

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

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

statusstring

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
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

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_idrequiredstring

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
idstring

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

typestring

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

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

statusstring

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
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard