Link Search Menu Expand Document

Bank Accounts

Bank Accounts are used to get money in and out of a Centrapay account. Money is moved by creating “Top Up” or “Withdrawal” Funds Transfers.

Bank accounts must be “direct debit authorized” before they can be used for a Top Up and they must be “verified” before top up funds are released. Bank accounts do not require “direct debit authorization” or “verification” in order to perform a Withdrawal. A 4-digit code from any recent Centrapay-initiated bank transaction can be used to verify a bank account.

Contents

Creating a bank account

A bank account can be created with or without direct debit authorized. By including directDebitAuthority, the user accepts our Direct Debit terms and has authority to operate this account.

POST /api/bank-accounts

Create without direct debit authorized

curl -X POST https://service.centrapay.com/api/bank-accounts \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe"
  }'

Create with direct debit authorized

curl -X POST https://service.centrapay.com/api/bank-accounts \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe",
    "directDebitAuthority": {
      "phoneNumber": "+64212345678",
      "fullName": "John Doe",
      "emailAddress": "john.doe@gmail.com"
    }
  }'

Required Fields

Field Type Description
bankAccountNumber String The user’s bank account number
bankAccountName String The name on the bank account provided by the user

Optional Fields

Note, fields which have a star (✩) create a direct-debit authority and are required for Top Up. All fields below when specified are required together.

Field Type Description
phoneNumber String ✩ The user’s phone number.
fullName String ✩ The first and last name of the user.
emailAddress String ✩ The user’s email address.

Example response payload

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "directDebitAuthorized": true,
  "status": "created",
  "verified": false,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2020-06-12T01:17:46.499Z",
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Error Responses

Status Code Description
403 BANK_ACCOUNT_LIMIT_EXCEEDED The Centrapay account already has the max amount of bank accounts.
403 BANK_ACCOUNT_HOLDER_LIMIT_EXCEEDED The global maximum bank accounts for the provided bank account number has been reached.
403 DUPLICATE_BANK_ACCOUNT The Centrapay account already holds this bank account.

Adding a direct debit authority to a bank account

By using this endpoint, the user accepts our Direct Debit terms and has authority to operate this account.

POST /api/bank-accounts/{bankAccountId}/direct-debit-authorities

curl -X POST https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/direct-debit-authorities \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+64212345678",
    "fullName": "John Doe",
    "emailAddress": "john@doe.org"
  }'

Example response payload

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "directDebitAuthorized": true,
  "status": "created",
  "verified": false,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2020-06-12T01:17:46.499Z",
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Required Fields

Note, fields which have a star (✩) are required for Top Up. All fields below when specified are required together.

Field Type Description
phoneNumber String ✩ The user’s phone number.
fullName String ✩ The first and last name of the user.
emailAddress String ✩ The user’s email address.

Error Responses

Status Code Description
403 DIRECT_DEBIT_ALREADY_AUTHORIZED This bank authority cannot be changed as all fields have been set.

Get information about a bank account

GET /api/bank-accounts/{bankAccountId}

curl https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY \
  -H "X-Api-Key: $api_key"

Verify a bank account

Verification codes show up on statements when a user makes withdrawals and deposits. To verify an account, you need to direct the user to make a topup/withdrawal and then check their statement.

POST /api/bank-accounts/{bankAccountId}/verify

curl -X POST https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/verify \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "verificationCode": "1111"
  }'

Required Fields

Field Type Description
verificationCode String The code on the user’s bank statement.

Example response payload

{
  "verificationCode": "1111"
}

Error Responses

Status Code Description
403 BANK_ACCOUNT_ALREADY_VERIFIED The bank account is already verified.
403 VERIFICATION_CODE_INVALID The verification code is incorrect.
403 BANK_ACCOUNT_VERIFICATION_ATTEMPTS_EXCEEDED The bank account’s maximum failed verification attempts has been reached.
403 ACCOUNT_MISMATCH The top up / withdrawal and the bank account do not belong to the same account.

Verify a bank authority DEPRECATED

If you’re creating new interfaces, please work with our verify endpoint for bank accounts.

POST /api/bank-authorities/{bankAccountId}/verify

curl -X POST https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY/verify \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "verificationCode": "1111"
  }'

Required Fields

Field Type Description
verificationCode String The code on the user’s bank statement

Example response payload

{
  "verificationCode": "1111"
}

Example response payload

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "status": "created",
  "directDebitAuthorized": true,
  "verified": false,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2020-06-12T01:17:46.499Z",
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

List bank accounts

GET /api/accounts/{accountId}/bank-accounts

curl https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-accounts \
  -H "X-Api-Key: $api_key"

Example response payload

[
  {
    "id": "WRhAxxWpTKb5U7pXyxQjjY",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe",
    "status": "created",
    "verified": false,
    "directDebitAuthorized": true,
    "createdAt": "2020-06-12T01:17:46.499Z"
  },
  {
    "id": "b5URhAxxWpTKyxQjjY7pXW",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "Jane Doe",
    "status": "active",
    "verified": true,
    "directDebitAuthorized": true,
    "createdAt": "2020-06-12T01:17:46.499Z"
  }
]

List bank authorities DEPRECATED

If you’re creating new interfaces, please work with our list endpoint for bank accounts.

GET /api/bank-authorities

curl https://service.centrapay.com/api/bank-authorities \
  -H "X-Api-Key: $api_key"

Example response payload

[
  {
    "id": "WRhAxxWpTKb5U7pXyxQjjY",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe",
    "status": "created",
    "verified": false,
    "directDebitAuthorized": true,
    "createdAt": "2020-06-12T01:17:46.499Z"
  },
  {
    "id": "b5URhAxxWpTKyxQjjY7pXW",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "Jane Doe",
    "status": "active",
    "verified": true,
    "directDebitAuthorized": true,
    "createdAt": "2020-06-12T01:17:46.499Z"
  }
]

Creating a bank authority DEPRECATED

If you’re creating new interfaces, please work with our create endpoint for bank accounts.

Creating a bank authority both creates a new bank account and a direct debit authority.

By using this endpoint, the user accepts our Direct Debit terms and has authority to operate this account.

POST /api/bank-authorities

curl -X POST https://service.centrapay.com/api/bank-authorities \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "John Doe",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "phoneNumber": "+64212345",
    "directDebitAuthorized": true,
    "emailAddress": "John.doe@email.com",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe"
  }'

Required Fields

Field Type Description
accountId String The id of the owning Centrapay Account.
fullName String The first and last name of the user
phoneNumber String The user’s phone number
emailAddress String The user’s email address
bankAccountNumber String The user’s bank account number
bankAccountName String The name on the bank account provided by the user

Example response payload

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "status": "created",
  "verified": false,
  "directDebitAuthorized": true,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2020-06-12T01:17:46.499Z",
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Error Responses

Status Code Description
403 BANK_AUTHORITY_LIMIT_EXCEEDED The account already has the max amount of bank accounts.
403 BANK_AUTHORITIES_FOR_BANK_ACCOUNT_EXCEEDED There are already two bank accounts for the provided bank account number, which is the maximum allowed.

Get information about a bank authority DEPRECATED

If you’re creating new interfaces, please work with our get endpoint for bank accounts.

GET /api/bank-authorities/{bankAccountId}

curl https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY \
  -H "X-Api-Key: $api_key"

Example response payload

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "status": "created",
  "directDebitAuthorized": true,
  "verified": false,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2020-06-12T01:17:46.499Z",
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}