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
- Operations
- Creating a Bank Account
- Adding a direct debit authority to a Bank Account
- Get information about a Bank Account
- Get Bank Account Balance EXPERIMENTAL
- Verify a Bank Account
- Verify a Bank Authority DEPRECATED
- List Bank Accounts
- List Bank Authorities DEPRECATED
- Creating a Bank Authority DEPRECATED
- Get information about a Bank Authority DEPRECATED
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 /
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_ | The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts. |
403 | BANK_ | The global maximum Bank Accounts for the provided Bank Account number has been reached. |
403 | DUPLICATE_ | 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 /
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_ | This bank authority cannot be changed as all fields have been set. |
403 | DIRECT_ | The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts. |
Get information about a Bank Account
GET /
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 /
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_ | The Bank Account Type does not support retrieval of a balance using Open Banking flows. |
403 | BANK_ | 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 /
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_ | The bank account is already verified. |
403 | VERIFICATION_ | The verification code is incorrect. |
403 | BANK_ | The bank account’s maximum failed verification attempts has been reached. |
403 | ACCOUNT_ | 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 /
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 /
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 /
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 /
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_ | The account already has the max amount of bank accounts. |
403 | BANK_ | 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 /
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": [
]
}