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.

Read

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

{
  "merchantid": 10544,
  "routes": [
    { "bankid": 1, "bankname": "ABSA",    "bankcode": "absa",    "primary": 88, "secondary": 91 },
    { "bankid": 3, "bankname": "FNB",      "bankcode": "fnb",     "primary": 88, "secondary": null },
    { "bankid": 5, "bankname": "Capitec",  "bankcode": "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 bankid or the more readable 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.