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.

List

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

{
  "merchantid": 10544,
  "accounts": [
    {
      "id": 88,
      "bankid": 3,
      "bankname": "FNB",
      "accountname": "Acme Online",
      "accountnumber": "••••0000",
      "branchcode": "250655",
      "accounttype": "cheque",
      "inuse": true
    }
  ]
}

Two fields to note:

• accountnumber is masked to the last 4 digits, always. The API never returns a full receiving account number — a partner integration is a broader exposure surface than a staff-only backoffice screen, so the full number is never sent back even though you can set it.
• 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 '{
    "bankid": 3,
    "accountname": "Acme Online",
    "accountnumber": "62000000000",
    "branchcode": "250655",
    "accounttype": "cheque"
  }'

The response echoes the created account — with its number masked:

{
  "id": 88,
  "bankid": 3,
  "bankname": "FNB",
  "accountname": "Acme Online",
  "accountnumber": "••••0000",
  "branchcode": "250655",
  "accounttype": "cheque",
  "inuse": false
}

accounttype is free text; "cheque" and "savings" are the conventional values.

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; it is returned masked.

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.