South African RTGS API

Integrate South African RTGS through the KeyBS Pay unified /v1/payouts REST endpoint. Authentication, request/response, sandbox, webhooks, errors and rate limits.

Speed

Same day

Currency

ZAR

Method key

rtgs-south-africa

Countries

Request sandbox key Full developer docs

South African RTGS integrates through the same POST /v1/payouts endpoint used for every KeyBS Pay corridor — you set "method": "rtgs-south-africa" and the router selects the South African RTGS rail. If South African RTGS is unavailable for the beneficiary bank at the moment of payment, the router falls back to the next eligible rail unless "strict": true is specified.

Authentication is via a Bearer API key issued from the KeyBS Pay dashboard. Every request MUST include an Idempotency-Key so retries after transient errors are safe. Webhook payloads carry an HMAC-SHA256 signature you must verify with your webhook secret before acting on the event.

Sandbox mode is available end-to-end: keys prefixed sk_test_ hit the sandbox environment, produce deterministic responses for testing, and never move real money. Production sk_live_ keys unlock the South African RTGS rail once your KYB is approved.

Corridor data

Corridor mechanics at a glance

Every KeyBS Pay payout follows the same operational contract; only the rail changes.

Endpoint

POST /v1/payouts

Rail method key

"method": "rtgs-south-africa"

Settlement currency

ZAR

Countries

Speed

Same day

Auth

Bearer token · Idempotency-Key header · request-signed HMAC (optional)

Rate limit

600 req/min per API key · burst 60/s

Webhooks

payout.created · payout.approved · payout.settled · payout.failed — HMAC-SHA256 signed with your webhook secret

TL;DR — key takeaways

POST /v1/payouts with method="rtgs-south-africa" routes through the South African RTGS rail.
Settlement: Same day in ZAR · countries: ZA.
Bearer-token auth · Idempotency-Key required · HMAC-signed webhooks.
Rate limit: 600 req/min per API key · burst 60/s.
Sandbox available via sk_test_ keys; production sk_live_ keys unlock the rail after KYB.

Request

POST /v1/payouts

POST https://api.keybs.io/v1/payouts
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": { "value": "1000.00", "currency": "USD" },
  "beneficiary": {
    "name": "Acme Trading Ltd",
    "account_number": "0123456789",
    "country": "ZA",
    "currency": "ZAR"
  },
  "method": "rtgs-south-africa",
  "reference": "INV-2026-0001",
  "purpose_code": "supplier_settlement",
  "metadata": { "invoice_id": "INV-2026-0001" }
}

Response

201 Created

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "status": "approved",
  "amount":       { "value": "1000.00", "currency": "USD" },
  "beneficiary_amount": { "value": "..." /* rail-specific FX */ },
  "rail":         "rtgs-south-africa",
  "estimated_settlement": "end_of_business_day",
  "reference":    "INV-2026-0001",
  "created_at":   "2026-02-14T09:12:00Z"
}

Webhook event

payout.settled — HMAC-signed

POST https://your-app.example/webhooks/keybs
X-KeyBS-Signature: t=1707902000,v1=<HMAC-SHA256(webhookSecret, timestamp + '.' + rawBody)>
Content-Type: application/json

{
  "id":   "evt_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "type": "payout.settled",
  "data": {
    "id":       "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
    "rail":     "rtgs-south-africa",
    "status":   "settled",
    "settled_at": "2026-02-14T09:12:07Z"
  }
}

Error format

422 Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code":    "beneficiary_verification_failed",
    "message": "Beneficiary account not found on South African RTGS",
    "rail":    "rtgs-south-africa",
    "retryable": false
  }
}

Ask KeyBS AI