PesaLink API

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

Speed

Real-time

Currency

KES

Method key

pesalink

Countries

Request sandbox key Full developer docs

PesaLink integrates through the same POST /v1/payouts endpoint used for every KeyBS Pay corridor — you set "method": "pesalink" and the router selects the PesaLink rail. If PesaLink 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 PesaLink 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": "pesalink"

Settlement currency

KES

Countries

Speed

Real-time

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="pesalink" routes through the PesaLink rail.
Settlement: Real-time in KES · countries: KE.
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": "KE",
    "currency": "KES"
  },
  "method": "pesalink",
  "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":         "pesalink",
  "estimated_settlement": "seconds",
  "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":     "pesalink",
    "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 PesaLink",
    "rail":    "pesalink",
    "retryable": false
  }
}

Ask KeyBS AI