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.

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.
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. Only present on quartz bank accounts.

Bank Account Type experimental

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

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 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
string required

The id of the owning Centrapay Account.
bankAccountNumber
string required

The user’s Bank Account number.
bankAccountName
string required

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.

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

{
  "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
string required

The user’s phone number.
fullName
string required

The first and last name of the user.
emailAddress
string required

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.

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

{
  "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.

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

{
  "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.

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

{
  "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
string required

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.

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

{
  "verificationCode": "1111"
}

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

List Bank Accounts

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

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

[
  {
    "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.

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

{
  "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.

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

{
  "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
string required

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.

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

{
  "verificationCode": "1111"
}

GET /api/bank-authorities

List Bank Authorities deprecated

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

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

[
  {
    "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
string required

The id of the owning Centrapay Account.
fullName
string required

The first and last name of the user.
phoneNumber
string required

The user’s phone number.
emailAddress
string required

The user’s email address.
bankAccountNumber
string required

The user’s Bank Account number.
bankAccountName
string required

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.

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

{
  "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.

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

{
  "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