Payment Routing

Payment routing decides, per bank, which receiving account a merchant's funds settle into. Each route has a primary account and an optional secondary (failover). Routing references the receiving accounts you manage in Receiving accounts.

Supported banks

GET /v1/merchants/{merchantId}/banks returns the active processing banks for the merchant's currency, each with its bankcode, bankname, and currency. AbsaPay is included only when the currency is ZAR and the merchant's AbsaPay setting is on.

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

{
  "banks": [
    { "bankcode": "absa", "bankname": "ABSA", "currency": "ZAR" },
    { "bankcode": "fnb", "bankname": "FNB", "currency": "ZAR" }
  ]
}

Use the bankcode when setting routes below.

Read

GET /v1/merchants/{merchantId}/payment-routing:

{
  "merchantid": 10544,
  "routes": [
    { "bankcode": "absa",    "bankname": "ABSA",    "primary": 88,   "secondary": 91 },
    { "bankcode": "fnb",     "bankname": "FNB",     "primary": 88,   "secondary": null },
    { "bankcode": "capitec", "bankname": "Capitec", "primary": null, "secondary": null }
  ]
}

The key rule to internalise:

A bank with primary = null is not supported for this merchant at the gateway.

There is no separate "enabled" flag. A bank is switched on by giving it a primary account and switched off by clearing it. In the example above, ABSA and FNB are supported (FNB with no failover); Capitec is not supported.

Write

PUT /v1/merchants/{merchantId}/payment-routing. Send the routes you want to set. Identify each bank by its bankcode.

curl -s -X PUT https://dev.boapi.ppgw.net/v1/merchants/10544/payment-routing \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "routes": [
      { "bankcode": "absa",    "primary": 88, "secondary": 91 },
      { "bankcode": "fnb",     "primary": 88 },
      { "bankcode": "capitec", "primary": null }
    ]
  }'

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

The rules:

• primary of null or 0 clears the route: the bank becomes unsupported for the merchant.
• secondary is ignored when primary is null. A failover with no primary is meaningless, so it is cleared rather than stored.
• Every referenced account must belong to the merchant. Pointing a route at an account id that isn't the merchant's is rejected with validation_failed.

The relationship to receiving accounts

Routing and receiving accounts are two halves of the same picture:

1. Add the receiving account; you get an account id.
2. Route a bank's primary (and optionally secondary) to that id.

An account that a route points at reports inuse: true and cannot be deleted until you clear it from routing. Work in that order (accounts first, routing second) and reverse it to tear down.