Create a Bank Account Verification

POST /bankaccountvalidator/v1/accounts/account_id/verifications

A bank account verification request allows merchants to send initiate the bank account verification request by sending some information about the customer to Paysafe, along with a few other parameters. The response to the POST request will contain a redirect URL by which the customer will be able to select a bank and verify that they, in fact, own the bank account(s).

To process a bank account verification, you must initiate a POST request to the verifications endpoint.

See our full API documentation for a complete description of the parameters required for the Payment request.
Request Example
curl -X https://api.test.paysafe.com/bankaccountvalidator/v1/accounts/123456789/verifications \
  -u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
  -H 'Content-Type: application/json' \
  -d '{
  "merchantRefNum": "1323563",
  "profile": {
    "firstName": "John",
    "middleName": "James",
    "lastName": "Smith",
    "locale": "en_CA"
  },
  "accountTypes": [
    "SAVING",
    "CHEQUING"
  ],
  "currencyCodes": [
    "CAD",
    "USD"
  ],
  "returnLinks": [
    {
      "rel": "default",
      "href": "https://mysite.com/return"
    }
  ],
  "bankscheme": "EFT"
}'

Prior to trying the example, you should:

  • Replace the account number (123456789) in the URL with the test account number you received.
  • Replace the API key (after the -u) with the API key you have received.
  • Provide a unique merchant reference number for each transaction.

The request contains the following parameters:

Element Child Element Type Required? Description
merchantRefNum

string
length<=255

Yes This is the merchant reference number created by the merchant and submitted as part of the request. A unique merchant reference number must be provided for each transaction.
profile object Yes This is some profile information about the customer.
firstName string
length<=80
Yes This is the customer's first name.
middleName string
length<=80
No This is the customer's middle name.
lastName string
length<=80
Yes This is the customer's last name.
locale enum No

This indicates the language of the user interface.Possible values are:

  • en_CA (English)
  • fr_CA (French)
accountTypes array No

This is the list of bank account types that will be presented. Possible values are:

  • SAVING
  • CHEQUING

If this parameter is not included, the default response will return EFT-eligible saving/chequing accounts.

currencyCodes

array

No

This the currency of the bank accounts that will be presented. Possible values are:

  • CAD
  • USD

If this parameter is not included, the default response will return CAD/USD currency accounts.

returnLinks array of objects Yes

These are URL endpoints to which to redirect the customer. You can customize the return URL based on the transaction status. The default value is mandatory.

rel enum Yes

This is the link type, allowing different endpoints to be targeted depending on the end state of the transaction. The link relation describes how this link relates to the previous call. Possible values are:

  • default – The default return URL that will be used if specific status return URL is not defined.
  • on_completed – Will be returned to this URL if the bank account validation request is completed.
  • on_failed – Will be returned to this URL if the bank account validation request fails.
href string Yes The actual URL to which the customer will be redirected.
bankScheme

enum

Yes

This is the bank scheme for which the merchant wants to validate the account. Possible values are:

  • ACH
  • EFT
Response Example
{
  "merchantRefNum": "1323563",
  "profile": {
    "firstName": "John",
    "middleName": "James",
    "lastName": "Smith",
    "locale": "en_CA"
  },
  "accountTypes": [
    "SAVING",
    "CHEQUING"
  ],
  "currencyCodes": [
    "CAD",
    "USD"
  ],
  "returnLinks": [
    {
      "rel": "default",
      "href": "https://mysite.com/return"
    }
  ],
  "bankscheme": "ACH",
  "id": "6a275b7c-6f11-4ed1-ae77-21071724574a",
  "sessionId": "MjM5NWRlMTQtNDE4Yy0xMWU5LWIyMTAtZDY2M2JkODczZDkz",
  "status": "INITIATED",
  "links": [
    {
      "rel": "redirect_bank_validation",
      "href": "https://api.paysafe.com/bankaccountvalidator/v1/redirect?sessionId=MjM5NWRlMTQtNDE4Yy0xMWU5LWIyMTAtZDY2M2JkODczZDkz"
    }
  ]
}

The response parameters not contained in the request are described below:

Element Child Element Type Description
id string
length<=36
Unique ID for this bank account verification operation. This ID can be used to look up the verification later.
sessionId string
length<=36
Unique session ID for this operation. This session ID is used in the redirect URL for the customer to validate their bank account.
status enum

The status of the request. Possible values are:

  • SUCCESS – The customer has validated their bank account successfully.
  • FAILED – The bank account validation has failed.
  • INITIATED – The merchant has initiated the bank account verification request.
  • INCOMPLETE – The bank account validation could not be completed successfully, e.g., due to user inactivity or session timeout.
links object This is an array of links related to the resource.
rel string

This is the link to the endpoint at the end of the transaction. Possible values are:

  • redirect_bank_validation
href string The actual URL to which the customer will be redirected.

Did you find this page useful?