Pesalink Developer Portal

Overview

This reference surface complements the Swagger UI available under /api-reference by outlining required headers, OAuth scopes, and example payloads. All endpoints are namespaced under `/v1` and rely on idempotency keys for safe retries.

Download the placeholder OpenAPI definition at /openapi.yaml and load it into tools like ReDoc, Swagger UI, or Postman for an interactive experience.

Payments

Create and manage instant credit transfers. Provide a unique `Idempotency-Key` header for each initiation call to guarantee exactly-once processing.

Method	Path	Description	OAuth Scope
POST	/v1/payments	Initiate an instant transfer	payments.write
GET	/v1/payments/{paymentId}	Fetch payment status	payments.read
POST	/v1/payments/{paymentId}/reversal	Submit reversal request	payments.write

json

{
  "sourceAccount": "34002349872",
  "destinationAccount": "017200234987",
  "amount": { "value": 25000, "currency": "KES" },
  "narration": "Invoice 1042",
  "metadata": {
    "customerRef": "POS-94833"
  }
}

Accounts

Validate beneficiary details and pull balances using account-level scopes. Responses include safe-to-display names for customer UIs.

Method	Path	Description	OAuth Scope
POST	/v1/accounts/verify	Validate account name	accounts.read
GET	/v1/accounts/{accountId}/balance	Retrieve available balance	accounts.read

json

{
  "accountNumber": "017200234987",
  "bankCode": "01",
  "response": {
    "matchConfidence": "HIGH",
    "accountName": "Pesalink Ventures Limited"
  }
}

Transactions

Query historical activity with filters on date ranges, status, and amount. Pagination uses RFC 5988 link headers.

Method	Path	Description	OAuth Scope
GET	/v1/transactions	List transactions with filters	transactions.read
GET	/v1/transactions/{transactionId}	Fetch a specific transaction	transactions.read

bash

curl "https://api.sandbox.pesalink.co.ke/v1/transactions?status=SETTLED&limit=25" \
  --header "Authorization: Bearer <token>" \
  --header "Accept: application/vnd.pesalink.v1+json"

Error Codes

Error responses share the structure below. Pair with request IDs when contacting support to accelerate triage.

json

{
  "errors": [
    {
      "code": "40102",
      "message": "Expired access token.",
      "requestId": "req_98f8abde"
    }
  ]
}

Code	Type	Description
40001	ValidationError	Missing required field.
40102	AuthenticationError	Expired access token.
40317	AuthorizationError	Insufficient OAuth scope.
40941	DuplicateRequest	Idempotency key re-used.
50303	ServiceUnavailable	Upstream network issue.