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

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

Bank Account Type experimental

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

TypeDescription
centrapayAllows topup and withdrawal of the centrapay.nzd asset type.
quartzAllows usage of the quartz.nzd asset type.

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.


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.


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

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

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}

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

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

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

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

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

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 'content-type: application/json' \
 -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

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

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

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}

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