Link Search Menu Expand Document
Centrapay Docs

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

Models

Bank Account

Mandatory Fields

Field Type Description
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.
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.
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.
createdBy CRN The User or API Key that created the Bank Account.
modifiedAt Timestamp When the Bank Account was updated.
modifiedBy CRN The User or API Key that updated the Bank Account.

Optional Fields

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.
test Boolean A flag which is present if the Bank Account is for testing.

Bank Account Approval Type Summary 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.

Fields

Name Type Description
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 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.

Bank Account Balance EXPERIMENTAL

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

Name Type Description
bankAccountId String The unique identifier of the Centrapay Bank Account.
balance BigNumber The Open Banking Bank Account balance.
currency String Currency code (eg. “NZD”).

Operations

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
accountId String The id of the owning Centrapay Account.
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.
type String The Bank Account Type to be created.
test Boolean A flag which is present if the Bank Account is for testing.

Example response payload 

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

  ]
}

Error Responses

Status Code Description
403 BANK_ACCOUNT_LIMIT_EXCEEDED The Centrapay account already has the max amount of directDebitAuthorized enabled 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,
  "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": [

  ]
}

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.
403 DIRECT_DEBIT_LIMIT_EXCEEDED The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts.

Get information about a Bank Account

GET /api/bank-accounts/{bankAccountId} 

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

Example response payload 

{
  "id": "d4a7cbd6818a87c51b97",
  "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-consent",
      "status": "approved",
      "updatedAt": "2021-11-08T21:52:39.915Z"
    }
  ],
  "type": "quartz",
  "test": true
}

Get Bank Account Balance EXPERIMENTAL

GET /api/bank-accounts/{bankAccountId}/balance 

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

Example response payload 

{
  "bankAccountId": "d4a7cbd6818a87c51b97",
  "balance": 1000,
  "currency": "NZD"
}

Error Responses

Status Code Description
403 BANK_BALANCE_NOT_SUPPORTED The Bank Account Type does not support retrieval of a balance using Open Banking flows.
403 BANK_AUTHORIZATION_INVALID The access token to retrieve the Bank Account Balance is no longer valid.

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 Top Up or 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",
  "approvals": [

  ]
}

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": "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"
  }
]

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

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

  ]
}

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

  ]
}