Receiving Accounts

A merchant's receiving accounts are the bank accounts its EFT funds settle into. This API lets you manage them; which account a given bank routes to is configured separately in Payment routing.

Supported banks

GET /v1/merchants/{merchantId}/receiving-account-banks returns the banks available for a receiving account, for the merchant's currency. Supply the bankcode when adding an account below. This list is distinct from the payment-routing banks (GET /v1/merchants/{merchantId}/banks).

curl -s https://dev.boapi.ppgw.net/v1/merchants/10544/receiving-account-banks \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "banks": [
    { "bankcode": "absa", "bankname": "ABSA", "currency": "ZAR" },
    { "bankcode": "capitec", "bankname": "Capitec", "currency": "ZAR" }
  ]
}

List

GET /v1/merchants/{merchantId}/receiving-accounts:

{
  "merchantid": 10544,
  "accounts": [
    {
      "id": 88,
      "bankcode": "fnb",
      "bankname": "FNB",
      "accountname": "Acme Online",
      "accountnumber": "62000000000",
      "branchcode": "250655",
      "accounttype": "cheque",
      "inuse": true
    }
  ]
}

• inuse is true when the account is referenced by an active payment route. An in-use account cannot be deleted until it is removed from routing first.

Add

POST /v1/merchants/{merchantId}/receiving-accounts. The bank must match the merchant's currency.

curl -s -X POST https://dev.boapi.ppgw.net/v1/merchants/10544/receiving-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bankcode": "fnb",
    "accountname": "Acme Online",
    "accountnumber": "62000000000",
    "branchcode": "250655",
    "accounttype": "cheque"
  }'

The response echoes the created account:

{
  "id": 88,
  "bankcode": "fnb",
  "bankname": "FNB",
  "accountname": "Acme Online",
  "accountnumber": "62000000000",
  "branchcode": "250655",
  "accounttype": "cheque",
  "inuse": false
}

Account types

accounttype is one of "cheque", "savings", or "public". The bankcode, accountname, accountnumber and branchcode are all required, for every account type. An account number that is absent or contains no digits is rejected.

For "public" (Public Recipient), the account name is the primary lookup used for payment. It must therefore be precisely what is registered at the bank(s) the receiving account will be used for. The account number is still required and is retained as the fallback: it is used to settle when no match is found on the name. Supply a valid account number, bank code and branch code as you would for any other account.

{
  "bankcode": "fnb",
  "accountname": "ACME ONLINE PTY LTD",
  "accountnumber": "62000000000",
  "branchcode": "250655",
  "accounttype": "public"
}

Update

PUT /v1/merchants/{merchantId}/receiving-accounts/{accountId} with the same body shape as add. Supply the full account number again if you are changing it.

Delete

DELETE /v1/merchants/{merchantId}/receiving-accounts/{accountId} soft-deletes the account (it is disabled, not physically removed).

{ "merchantid": 10544, "updated": 1 }

If the account is referenced by an active payment route, the delete is refused with validation_failed. Remove it from routing first, then delete it. This mirrors the backoffice guard and prevents a route from pointing at an account that no longer exists.