Link Search Menu Expand Document
Centrapay Docs

Funds Transfers

A funds transfer represents either a top up to or a withdrawal from a Centrapay wallet. Topping up a wallet consists of making a bank transfer from the user’s bank account to Centrapay. Once Centrapay has verified the transfer was successful a user will be given credit on their Centrapay wallet equal to the amount of the bank transfer.

Contents

Creating a top up

POST /api/topups 

curl -X POST https://service.centrapay.com/api/topups \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY"
  }'

Required Fields

Field Type Description
amount BigNumber Total amount of the transaction in cents
walletId String The id of the wallet
bankAuthorityId String The id of the bank account

Example response payload 

{
  "id": "hg2RfYTQ635tPBZEPJdCre",
  "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
  "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
  "accountId": "aBc932S9182qwCDqwer",
  "type": "topup",
  "amount": "10000",
  "status": "created",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-01T12:30:00.000Z"
}

Error Responses

Status Code Description
403 BANK_AUTHORITY_WALLET_MISMATCH The wallet and the bank account for the top up request do not belong to the same account.
403 MAX_INFLIGHT_TOPUPS_EXCEEDED The bank account already has ten pending top ups, which is the maximum a bank authority can have at any one time.
403 MAX_INFLIGHT_TOPUP_AMOUNT_EXCEEDED The top up can not be created because it is above the max amount of funds a bank account can have pending at any one time. The max amount is $1000.00 for verified bank accounts and $100.00 for non-verified bank accounts.
403 QUOTA_EXCEEDED The topup exceeds one or more top up quota limits. See Quota Error Response.
403 DIRECT_DEBIT_NOT_AUTHORIZED Bank account requires authorization for top up. See bank accounts direct debit endpoint.
403 INVALID_WALLET_TYPE The wallet type does not support top ups. See settlement wallets.

Get a top up by id

GET /api/topups/{topupId} 

curl https://service.centrapay.com/api/topups/WRhAxxWpTKb5U7pXyxQjjY \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "hg2RfYTQ635tPBZEPJdCre",
  "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
  "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
  "accountId": "aBc932S9182qwCDqwer",
  "type": "topup",
  "amount": "10000",
  "status": "created",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-01T12:30:00.000Z"
}

List top ups for authorized accounts

GET /api/topups 

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

Example response payload 

[
  {
    "id": "5thg2RPBZEfYTPJdQ63Cre",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
    "accountId": "aBc932S9182qwCDqwer",
    "type": "topup",
    "amount": "10000",
    "status": "created",
    "createdAt": "2020-05-01T12:30:00.000Z",
    "updatedAt": "2020-05-01T12:30:00.000Z"
  },
  {
    "id": "hg2RfYTQ635tPBZEPJdCre",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
    "accountId": "aBc932S9182qwCDqwer",
    "type": "topup",
    "amount": "10000",
    "status": "created",
    "createdAt": "2020-05-01T12:30:00.000Z",
    "updatedAt": "2020-05-01T12:30:00.000Z"
  }
]

List top ups for an account EXPERIMENTAL

GET /api/accounts/{accountId}/topups 

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

Example response payload 

[
  {
    "id": "5thg2RPBZEfYTPJdQ63Cre",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
    "accountId": "aBc932S9182qwCDqwer",
    "type": "topup",
    "amount": "10000",
    "status": "created",
    "createdAt": "2020-05-01T12:30:00.000Z",
    "updatedAt": "2020-05-01T12:30:00.000Z"
  },
  {
    "id": "hg2RfYTQ635tPBZEPJdCre",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
    "accountId": "aBc932S9182qwCDqwer",
    "type": "topup",
    "amount": "10000",
    "status": "created",
    "createdAt": "2020-05-01T12:30:00.000Z",
    "updatedAt": "2020-05-01T12:30:00.000Z"
  }
]

Creating a Withdrawal EXPERIMENTAL

POST /api/withdrawals 

curl -X POST https://service.centrapay.com/api/withdrawals \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
    "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY"
  }'

Required Fields

Field Type Description
amount BigNumber Total amount of the transaction in cents
walletId String The id of the wallet
bankAuthorityId String The id of the bank account

Example response payload 

{
  "id": "hg2RfYTQ635tPBZEPJdCre",
  "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
  "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
  "accountId": "aBc932S9182qwCDqwer",
  "type": "withdrawal",
  "amount": "10000",
  "status": "created",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-01T12:30:00.000Z"
}

Error Responses

Status Code Description
403 BANK_AUTHORITY_WALLET_MISMATCH The wallet and the bank account for the withdrawal request do not belong to the same account.
403 INSUFFICIENT_WALLET_BALANCE The wallet balance is less than the required amount.
403 INVALID_WALLET_TYPE The wallet type does not support withdrawals. See settlement wallets.

Get a Withdrawal by id EXPERIMENTAL

GET /api/withdrawals/{withdrawalId} 

curl https://service.centrapay.com/api/withdrawals/WRhAxxWpTKb5U7pXyxQjjY \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "hg2RfYTQ635tPBZEPJdCre",
  "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
  "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
  "accountId": "aBc932S9182qwCDqwer",
  "type": "withdrawal",
  "amount": "10000",
  "status": "created",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-01T12:30:00.000Z"
}

List Withdrawals for an account EXPERIMENTAL

Returns a paginated list of Withdrawals for an account.

GET /api/accounts/{accountId}/withdrawals 

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

Example response payload 

{
  "items": [
    {
      "id": "5thg2RPBZEfYTPJdQ63Cre",
      "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
      "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
      "accountId": "aBc932S9182qwCDqwer",
      "type": "withdrawal",
      "amount": "10000",
      "status": "created",
      "createdAt": "2020-05-01T12:30:00.000Z",
      "updatedAt": "2020-05-01T12:30:00.000Z"
    },
    {
      "id": "hg2RfYTQ635tPBZEPJdCre",
      "walletId": "Te2uDM7xhDLWGVJU3nzwnh",
      "bankAuthorityId": "FRhAzzWpTKb5U7pZygQjjY",
      "accountId": "aBc932S9182qwCDqwer",
      "type": "withdrawal",
      "amount": "10000",
      "status": "done",
      "createdAt": "2020-05-01T12:30:00.000Z",
      "updatedAt": "2020-05-01T12:30:00.000Z"
    }
  ]
}