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

POST https://service.centrapay.com/api/bank-accounts

An example of a minimal POST to create a bank account.

curl -X POST "https://service.centrapay.com/api/bank-accounts" \
  -H "x-api-key: 1234" \
  -H "content-type: application/json" \
  -d '{
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe"
  }'

An example of a minimal POST to create a bank account and a direct debit authority.

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

curl -X POST "https://service.centrapay.com/api/bank-accounts" \
  -H "x-api-key: 1234" \
  -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 https://service.centrapay.com/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: 1234" \
  -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 https://service.centrapay.com/api/bank-accounts/${id}

curl -X GET https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY \
  -H "x-api-key: 1234"

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 https://service.centrapay.com/api/bank-accounts/${bankAccountId}/verify

curl -X POST "https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/verify" \
  -H "x-api-key: 1234" \
  -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 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.

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 https://service.centrapay.com/api/bank-authorities/${bankAccountId}/verify

curl -X POST "https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY/verify" \
  -H "x-api-key: 1234" \
  -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 https://service.centrapay.com/api/accounts/${accountId}/bank-accounts

curl -X GET "https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-accounts" \
  -H "x-api-key: 1234"

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 https://service.centrapay.com/api/bank-authorities

curl -X GET "https://service.centrapay.com/api/bank-authorities" \
  -H "x-api-key: 1234"

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 https://service.centrapay.com/api/bank-authorities

curl -X POST "https://service.centrapay.com/api/bank-authorities" \
  -H "x-api-key: 1234" \
  -H "content-type: application/json" \
  -d '{
    "fullName": "John Doe",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "phoneNumber": "+64212345678",
    "directDebitAuthorized": true,
    "emailAddress": "John.doe@email.com",
    "bankAccountNumber": "12-1234-1234567-123",
    "bankAccountName": "John Doe"
  }'

Required Fields

Field Type Description
accountId String The account id of the user
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 https://service.centrapay.com/api/bank-authorities/${id}

curl -X GET https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY \
  -H "x-api-key: 1234"

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",
}