Bank Accounts - Centrapay Docs

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 API .

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.

Bank Account Model

Attributes

id
string
The Bank Account’s unique identifier.
bankAccountNumber
string
The user’s Bank Account number.
bankAccountName
string
The name on the Bank Account provided by the user.
preferredBankAccountName
string
The preferred bank account name for the Bank Account provided by the user. This is only available on Bank Accounts of type quartz.
accountId
string
The id of the owning Centrapay Account API .
status
string
The current status of the Bank Account.
verified
boolean
Flag indicating the Bank Account is verified, allowing it to be used to Top Up.
type
string
The Bank Account Type of the bank, defaults to centrapay.
directDebitAuthority
object
A direct-debit authority. By including directDebitAuthority, the user accepts our Direct Debit terms and has authority to operate this account.
directDebitAuthorized
boolean
Flag indicating the user accepts our Direct Debit terms and has authority to operate this account.
approvals
array
A list of Bank Account Approval Type Summaries.
createdAt
timestamp
When the Bank Account was created.
modifiedAt
timestamp
When the Bank Account was updated.
createdBy
crn
The User or API Key that created the Bank Account.
modifiedBy
crn
The User or API Key that updated the Bank Account.
test
boolean
A flag which is present if the Bank Account is for testing.
enduringPaymentConsentAuthorized
boolean
Flag indicating whether the bank account can be used for creating enduring payment consents API . Only present on quartz bank accounts.

Bank Account Type experimental

Types of bank accounts to allow access to different Asset Types API .

Type	Description
centrapay	Allows topup and withdrawal of the `centrapay.nzd` asset type.
quartz	Allows usage of the `quartz.nzd` asset type.

Direct Debit Authority Model

A direct-debit authority is required to be able to Top Up a Bank Account. By including directDebitAuthority, the user accepts our Direct Debit terms and has authority to operate this account.

Attributes

phoneNumber
string
The user’s phone number.
fullName
string
The first and last name of the user.
emailAddress
string
The user’s email address.

Bank Account Approval Type Summary Model experimental

A summary of the Bank Account Approvals API for a Bank Account. There is one object per type of Bank Account Approval, which provides a summary of the approval status.

Attributes

type
string
The type of Bank Account Approval Summary.
status
string
The summarized status of the Bank Account Approvals. Supported values are pending, approved and declined.
updatedAt
timestamp
When the Bank Account Approval Summary was updated.

Bank Account Balance Model experimental

The Bank Account balance, retrieved using Open Banking flows. The supported Bank Account type is quartz.

Attributes

bankAccountId
string
The unique identifier of the Centrapay Bank Account.
balance
bignumber
The Open Banking Bank Account balance.
currency
string
Currency code (eg. “NZD”).

POST/api/bank-accounts

Create 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.

phone, fullName and emailAddress are all required to create a direct-debit authority. This is required to be able to Top Up a Bank Account.

Attributes

accountId
stringrequired
The id of the owning Centrapay Account API .
bankAccountNumber
stringrequired
The user’s Bank Account number.
bankAccountName
stringrequired
The name on the Bank Account provided by the user.
directDebitAuthority
object
A direct-debit authority. By including directDebitAuthority, the user accepts our Direct Debit terms and has authority to operate this account.
type
string
The Bank Account Type of the bank, defaults to centrapay.
test
boolean
A flag which is present if the Bank Account is for testing.

Errors

BANK_ACCOUNT_LIMIT_EXCEEDED
403
The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts.
BANK_ACCOUNT_HOLDER_LIMIT_EXCEEDED
403
The global maximum Bank Accounts for the provided Bank Account number has been reached.
DUPLICATE_BANK_ACCOUNT
403
The Centrapay account already holds this Bank Account.

Request

POST/api/bank-accounts

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

Response

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "directDebitAuthorized": true,
  "status": "created",
  "verified": false,
  "type": "centrapay",
  "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",
  "approvals": []
}

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

Add 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.

Attributes

phoneNumber
stringrequired
The user’s phone number.
fullName
stringrequired
The first and last name of the user.
emailAddress
stringrequired
The user’s email address.

Errors

DIRECT_DEBIT_ALREADY_AUTHORIZED
403
This bank authority cannot be changed as all fields have been set.
DIRECT_DEBIT_LIMIT_EXCEEDED
403
The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts.

Request

POST/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/direct-debit-authorities

curl -X POST \
 https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/direct-debit-authorities \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "phoneNumber": "+64212345678",
 "fullName": "John Doe",
 "emailAddress": "john.doe@gmail.com"
}
'

Response

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "directDebitAuthorized": true,
  "status": "created",
  "verified": false,
  "type": "centrapay",
  "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",
  "approvals": []
}

GET/api/bank-accounts/{bankAccountId}

Get Bank Account

This endpoint allows you to retrieve information about a Bank Account.

Request

GET/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY

curl -X GET \
 https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY \
 -H 'x-api-key: <TOKEN>'

Response

{
  "id": "WRhAxxWpTKb5U7pXyxQjjY",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "status": "created",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "John Doe",
  "directDebitAuthorized": false,
  "bankRegion": "nz",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "createdAt": "2022-07-18T02:26:39.477Z",
  "verified": false,
  "modifiedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "modifiedAt": "2022-07-18T02:26:39.477Z",
  "approvals": [
    {
      "type": "account-information-consent",
      "status": "approved",
      "updatedAt": "2021-11-08T21:52:39.915Z"
    }
  ],
  "type": "quartz",
  "test": true
}

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

Get Bank Account Balance experimental

This endpoint allows you to retrieve the balance of a Bank Account.

Request

GET/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-account-balances

curl -X GET \
 https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-account-balances \
 -H 'x-api-key: <TOKEN>'

Response

{
  "items": [
    {
      "bankAccountId": "b3f9ba1abff64775877d4a2fb073b123",
      "bankAccountNumber": "12-1234-1234567-123",
      "balance": "101.00",
      "availableBalance": "101.00",
      "test": true
    }
  ],
  "nextPageKey": "48a16140-24d2-4aec-b52f-a9d4f8f23876"
}

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

Verify 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 Top Up or Withdrawal and then check their statement.

Attributes

verificationCode
stringrequired
The code on the user’s bank statement.

Errors

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

Request

POST/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/verify

curl -X POST \
 https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/verify \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "verificationCode": "1111"
}
'

Response

{
  "verificationCode": "1111"
}

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

List Bank Accounts

This endpoint allows you to list the Bank Accounts for an account.

Request

GET/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-accounts

curl -X GET \
 https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/bank-accounts \
 -H 'x-api-key: <TOKEN>'

Response

[
  {
    "id": "XZbPLViMzekVBbF7QMqgaY",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "status": "created",
    "bankAccountNumber": "02-0500-0568903-097",
    "bankAccountName": "Pocket Money",
    "directDebitAuthorized": false,
    "bankRegion": "nz",
    "createdBy": "crn::user:57142ecc-e5e4-456a-8312-1fad4fdef3c7",
    "createdAt": "2022-04-19T05:43:40.425Z",
    "verified": false,
    "modifiedBy": "crn::user:57142ecc-e5e4-456a-8312-1fad4fdef3c7",
    "modifiedAt": "2022-04-19T05:43:40.425Z",
    "approvals": [],
    "type": "quartz",
    "test": true
  },
  {
    "id": "3Kfdm8cuW1W6f8AoWJREs4",
    "accountId": "Jaim1Cu1Q55uooxSens6yk",
    "status": "created",
    "bankAccountNumber": "00-1213-1231299-999",
    "bankAccountName": "Jean",
    "directDebitAuthorized": false,
    "bankRegion": "nz",
    "createdBy": "crn::user:57142ecc-e5e4-456a-8312-1fad4fdef3c7",
    "createdAt": "2022-02-22T03:27:57.138Z",
    "verified": false,
    "modifiedBy": "crn::user:57142ecc-e5e4-456a-8312-1fad4fdef3c7",
    "modifiedAt": "2022-02-22T03:27:57.138Z",
    "approvals": [
      {
        "type": "settlement",
        "status": "pending",
        "updatedAt": "2021-11-08T21:52:39.915Z"
      }
    ],
    "type": "centrapay"
  }
]

POST/api/bank-accounts/{bankAccountId}/set-preferred-name

Set Preferred Bank Account Name

Errors

INVALID_BANK_ACCOUNT_TYPE
403
The type of bank account is not supported for this operation. Only quartz bank accounts are supported.

Request

POST/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/set-preferred-name

curl -X POST \
 https://service.centrapay.com/api/bank-accounts/WRhAxxWpTKb5U7pXyxQjjY/set-preferred-name \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "preferredBankAccountName": "Everyday Account"
}
'

Response

{
  "activityNumber": 1,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "bankAccountId": "WRhAxxWpTKb5U7pXyxQjjY",
  "type": "set-preferred-bank-account-name",
  "preferredBankAccountName": "Everyday Account",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

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

Archive Bank Account

Archives the supplied bank account. This endpoint is currently only supported for quartz bank accounts.

Request

POST/api/bank-accounts/b5URhAxxWpTKyxQjjY7pXW/archive

curl -X POST \
 https://service.centrapay.com/api/bank-accounts/b5URhAxxWpTKyxQjjY7pXW/archive \
 -H 'x-api-key: <TOKEN>'

Response

{
  "id": "b5URhAxxWpTKyxQjjY7pXW",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "bankAccountNumber": "12-1234-1234567-123",
  "bankAccountName": "Jane Doe",
  "preferredBankAccountName": "Everyday Account",
  "balance": "123",
  "availableBalance": "100",
  "status": "archived",
  "verified": true,
  "directDebitAuthorized": true,
  "createdAt": "2020-06-12T01:17:46.499Z",
  "test": true
}

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

Verify Bank Authority deprecated

If you’re creating new interfaces, please work with Verify Bank Account.

Attributes

verificationCode
stringrequired
The code on the user’s bank statement.

Errors

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

Request

POST/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY/verify

curl -X POST \
 https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY/verify \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "verificationCode": "1111"
}
'

Response

{
  "verificationCode": "1111"
}

GET/api/bank-authorities

List Bank Authorities deprecated

If you’re creating new interfaces, please work with List Bank Accounts.

Request

GET/api/bank-authorities

curl -X GET \
 https://service.centrapay.com/api/bank-authorities \
 -H 'x-api-key: <TOKEN>'

Response

[
  {
    "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",
    "approvals": []
  },
  {
    "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",
    "approvals": [
      {
        "type": "settlement",
        "status": "pending",
        "updatedAt": "2021-11-08T21:52:39.915Z"
      }
    ]
  }
]

POST/api/bank-authorities

Create Bank Authority deprecated

If you’re creating new interfaces, please work with Create Bank Account.

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.

Attributes

accountId
stringrequired
The id of the owning Centrapay Account API .
fullName
stringrequired
The first and last name of the user.
phoneNumber
stringrequired
The user’s phone number.
emailAddress
stringrequired
The user’s email address.
bankAccountNumber
stringrequired
The user’s Bank Account number.
bankAccountName
stringrequired
The name on the Bank Account provided by the user.

Errors

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

Request

POST/api/bank-authorities

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

Response

{
  "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",
  "approvals": []
}

GET/api/bank-authorities/{bankAccountId}

Get Bank Authority deprecated

If you’re creating new interfaces, please work with Get Bank Account.

Errors

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

Request

GET/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY

curl -X GET \
 https://service.centrapay.com/api/bank-authorities/WRhAxxWpTKb5U7pXyxQjjY \
 -H 'x-api-key: <TOKEN>'

Response

{
  "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",
  "approvals": []
}

Bank Account Model

Attributes

id

bankAccountNumber

bankAccountName

preferredBankAccountName

accountId

status

verified

type

directDebitAuthority

directDebitAuthorized

approvals

createdAt

modifiedAt

createdBy

modifiedBy

test

enduringPaymentConsentAuthorized

Bank Account Type experimental

Direct Debit Authority Model

Attributes

phoneNumber

fullName

emailAddress

Bank Account Approval Type Summary Model experimental

Attributes

type

status

updatedAt

Bank Account Balance Model experimental

Attributes

bankAccountId

balance

currency

Create Bank Account

Attributes

accountId

bankAccountNumber

bankAccountName

directDebitAuthority

type

test

Errors

BANK_ACCOUNT_LIMIT_EXCEEDED

BANK_ACCOUNT_HOLDER_LIMIT_EXCEEDED

DUPLICATE_BANK_ACCOUNT

Add Direct Debit Authority to a Bank Account

Attributes

phoneNumber

fullName

emailAddress

Errors

DIRECT_DEBIT_ALREADY_AUTHORIZED

DIRECT_DEBIT_LIMIT_EXCEEDED

Get Bank Account

Get Bank Account Balance experimental

Verify Bank Account

Attributes

verificationCode

Errors

BANK_ACCOUNT_ALREADY_VERIFIED

VERIFICATION_CODE_INVALID

BANK_ACCOUNT_VERIFICATION_ATTEMPTS_EXCEEDED

ACCOUNT_MISMATCH

List Bank Accounts

Set Preferred Bank Account Name

Errors

INVALID_BANK_ACCOUNT_TYPE

Archive Bank Account

Verify Bank Authority deprecated

Attributes

verificationCode

Errors

BANK_ACCOUNT_ALREADY_VERIFIED

VERIFICATION_CODE_INVALID

BANK_ACCOUNT_VERIFICATION_ATTEMPTS_EXCEEDED

ACCOUNT_MISMATCH

List Bank Authorities deprecated

Create Bank Authority deprecated