Bank Account Verification

Introduction

Embedded Wallet customers are allowed to use only bank accounts with verified ownership. This requirement is valid for both legal entities and regular customers.

The supported verification process depends on the customer type and country:

• Regular customers can verify their account through the following means:
  • Perform a bank wire deposit. Paysafe checks the deposit origin in the bank statement and performs a name matching to verify ownership.
  • Add bank account using the Instrument Verification Service.
• Legal entities must use Manual Bank Account Verification.

Instrument Verification Service

The Instrument Verification service is part of the Embedded Wallet product, and it is designed to enable payment operations (deposits and withdrawals) via payment institutions in a safe and compliant way. The solution provides verification of bank accounts and allows their use as Embedded Wallet payment instruments. Hence, throughout the document, we will be using the terms bank account and payment instrument interchangeably.

Payment Instrument Verification service provides a uniform interface to perform Bank Account Verification.

It consists of:

• REST APIs to trigger and manage the verification process.
• UI application hosting customer-facing interfaces.

The core of the Payment Instrument Verification process is:

• Collection of customer's payment instrument details.
• Confirmation of customer's ownership over the instrument.
• Confirmation of the instrument's validity.

The process of payment instrument verification may vary depending on the country, the type of the payment instrument, and other factors.

Paysafe leverages certified third-party providers, that perform the verification process in a compliant manner.

For the USA region, the third-party verification provider is PLAID, and we will be using it below for the sake of having more tangible and concrete examples.

The API provided to the merchant is uniform and agnostic to the underlying third-party provider or other implementation details.

Instrument Verification Session

Each payment instrument verification is carried out in a verification session. The payment instrument verification session statuses are shown below:

The flow begins with the Merchant creating a new payment instrument verification session. The initial status of the session is ACTIVE.

The customer must be redirected to the redirectUrl contained in the session object.

• During the AWAITING_USER_INPUT status the user is expected to provide more information or perform some action in order to proceed with the verification process.
• During the ONGOING_VERIFICATION status the control is on Paysafe side.

Once all the required input is collected Paysafe will verify the account ownership.

note

There might be transitions between AWAITING_USER_INPUT and ONGOING_VERIFICATION statuses. The verification process might require additional user input at a later point in the process and some steps might take a relatively long time to complete (e.g. a few days). That means that the user may need to close the UI and return to it later.

The merchant should provide the ability to the customer to continue sessions switched to AWAITING_USER_INPUT status. Paysafe provides an API for getting verification sessions with a given status. The number of simultaneous open sessions is limited.

The session status is updated to COMPLETED, when the payment instrument is successfully created and verified or to FAILED when the payment instrument verification process fails.

Instrument Verification Session Steps

1. The merchant's customer initiates a request for verifying bank account.
2. Merchant creates PIV session. The initial session status is ACTIVE.

POST https://api.paysafe.com/digitalwallet/v1/customers/1003900/instrument-verifications

Request

{
  "returnUrl": "https://merchantsite.com/verification",
  "instrumentType": "US_BANK_ACCOUNT"
}

---

Response

{
  "customerId": "1003900",
  "id": "2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368",
  "secureCode": "c2Rmc2ZzZmRzZGZzZGY=",
  "redirectUrl": "https://<paysafe-piv-ui-app>/api/v1/instruments/verification/{id}/initiate",
  "returnUrl" : "https://merchantsite.com/verification",
  "creationTime": "2019-08-24T14:15:22Z",
  "expirationTime": "2019-08-24T14:15:22Z",
  "instrumentType": "US_BANK_ACCOUNT",
  "sessionStatus": "ACTIVE"
}

3. Merchant prepares the secureCodeHash parameter's value following these steps:

   1. Decodes the base64 encoded secureCode string to a byte array.
   2. Hash the byte array with the sha512 algorithm.
   3. Encodes the produced hashed byte array with base64 algorithm.

4. Merchant redirects the customer to the redirectUrl with query parameter secureCodeHash=MmNiNTj... and path variable the sessionId {id}=2cb56b2749af....

   For example: https://<paysafe-piv-ui-app>/api/v1/instruments/verification/{id}/initiate?secureCodeHash=MmNiNTj...

   tip

   User-facing API and SDK does not require secureCodeHash parameter.

5. Customer passes the required steps for bank account selection in the Paysafe verification UI app.

6. When the customer completes the steps and clicks Continue button the Paysafe verification UI app navigates to waiting screen that is polling for information related to the customer's instrument.

   • The session status is updated to ONGOING_VERIFICATION.
   • The customer is redirected to the returnUrl.
   • If any error has occurred during instrument creation process the session status will be set to FAILED.

Getting Instrument Verification Session Status

1. Merchant can check all customer verification sessions by calling the following endpoint:

GET https://api.paysafe.com/digitalwallet/v1/customers/1003900/instrument-verifications

Response

{
  "instrumentVerifications": [
    {
      "customerId": "1003900",
      "id": "2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368",
      "redirectUrl": "https://<paysafe-piv-ui-app>/api/v1/instruments/verification/{id}/initiate",
      "returnUrl" : "https://merchantsite.com/verification",
      "creationTime": "2019-08-24T14:15:22Z",
      "expirationTime": "2019-08-24T16:15:22Z",
      "instrument": {
      "id": "1003900",
      "instrumentType": "US_BANK_ACCOUNT"
    },
      "instrumentType": "US_BANK_ACCOUNT",
      "sessionStatus": "COMPLETED"
    }
  ],
  "meta": {
  "numberOfRecords": 1,
  "limit": 10,
  "page": 0
  }
}

2. Merchant can get single verification session by sessionId using the following endpoint:

GET https://api.paysafe.com/digitalwallet/v1/customers/1003900/instrument-verifications/2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368

Response

{
  "customerId": "1003900",
  "id": "2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368",
  "secureCode": "c2Rmc2ZzZmRzZGZzZGY=",
  "redirectUrl": "https://<paysafe-piv-ui-app>/api/v1/instruments/verification/2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368/initiate",
  "returnUrl" : "https://merchantsite.com/verification",
  "creationTime": "2019-08-24T14:15:22Z",
  "expirationTime": "2019-08-24T16:15:22Z",
  "instrument": {
    "id": "1003900",
    "instrumentType": "US_BANK_ACCOUNT",
  },
  "instrumentType": "US_BANK_ACCOUNT",
  "sessionStatus": "COMPLETED"
}

3. Merchant will be notified via Webhook when the instrument is successfully created or its status is changed. The following notification will be sent to the merchant:

POST https://<merchant callback URL>/instruments/events

{
  "id": "100001",
  "customerId": "1003900",
  "operationType": "CREATE",
  "timestamp": "2021-07-15T17:54:12Z",
  "instrument": {
    "id": "100001",
    "customerId": "1003900",
    "instrumentType": "US_BANK_ACCOUNT",
    "status": "VERIFIED"
  }
}

Manual Bank Account Verification

Legal entities must submit bank account statement issued by the bank. This statement is submitted through API and manually verified by Paysafe.

Below are the verification process steps:

1. Add the new instrument for the customer. The instruments added through the API are in UNVERIFIED state.
2. Submit the bank account statement confirming ownership through the API.
3. Paysafe operator checks the submitted statement and updates the instrument status.
4. Merchants receive a webhook for instrument status change to VERIFIED or poll for status using the instrument management API.

warning

Instruments might be REJECTED by Paysafe. In such cases contact Paysafe support for details.

API Examples

1. Add payment instrument to customer 5000001.

POST https://api.paysafe.com/digitalwallets/v1/customers/5000001/instruments/

Request

{
  "instrumentType": "SEPA_BANK_ACCOUNT",
  "accountHolderName": "John Doe",
  "iban": "NL94RABO7762494464",
  "bic": "RABONL2U"
}

---

Response

{
  "id": "2323213",
  "customerId": "500001",
  "instrumentType": "SEPA_BANK_ACCOUNT",
  "accountHolderName": "John Doe",
  "iban": "NL94RABO7762494464",
  "bic": "RABONL2U",
  "status": "UNVERIFIED"
}

2. Submit bank account statement document to Paysafe.

POST https://api.paysafe.com/digitalwallets/v1/customer-legal-entities/{customerId}

{
  "kybDocuments": [
    {
      "type": "COMPANY_BANK_STATEMENT",
      "documentUrls": ["https://upload.wikimedia.org/wikipedia/commons/3/bank_statement.pdf"]
    }
  ]
}

3. Instrument verification webhook confirming VERIFIED state is sent when the statement has been reviewed by the Paysafe service agents.

POST https://www.merchantsite.com/instruments/events

{
  "id": "98329382947",
  "timestamp": "2021-07-15T17:54:12Z",
  "operationType": "Update",
  "instrument": {
    "id": "2323213",
    "customerId": "5000001",
    "instrumentType": "SEPA_BANK_ACCOUNT",
    "status": "VERIFIED"
  }
}

4. Payment instrument details can be obtained using the webhook information. Example request for instrument 2323213 of customer 5000001.

GET https://api.paysafe.com/digitalwallets/v1/customers/5000001/instruments/SEPA_BANK_ACCOUNT/2323213

{
  "id": "2323213",
  "customerId": "500001",
  "instrumentType": "SEPA_BANK_ACCOUNT",
  "accountHolderName": "John Doe",
  "iban": "NL94xxxxxxxxxxx464",
  "bic": "RABONL2U",
  "status": "UNVERIFIED"
}