Skip to main content
POST
/
payments-api-service
/
v1
/
payouts
Initiate Payout
curl --request POST \
  --url https://sandbox.waftpay.io/api/payments-api-service/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Custom-Signature: <x-custom-signature>' \
  --data '
{
  "transaction": {
    "reference": "TXN213687756272200",
    "amount": 1000,
    "currency": "KES",
    "description": "Test description",
    "service_code": "MPESAB2C",
    "timestamp": "2025-01-21T12:30:10Z"
  },
  "originator": {
    "msisdn": "254708374149",
    "channel": "USSD",
    "country": "KE",
    "name": "John Doe",
    "purpose": "Salary Payment"
  },
  "recipient": {
    "reference": "INVJMA02",
    "account": "254708374149"
  },
  "callback_url": "https://merchant.example.com/callbacks/payout",
  "meta": {}
}
'
{
  "status": "<string>",
  "code": "<string>",
  "description": "<string>",
  "data": {
    "amount": 123,
    "transaction_reference": "<string>",
    "payment_uuid": "<string>",
    "payment_reference": "<string>",
    "time_received": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Use the Payouts API to disburse funds from your Waftpay wallet to a customer, vendor, or partner. Payouts are asynchronous: you receive an acceptance response immediately, then a final outcome via webhook. This call is idempotent. Reuse the same transaction.reference to safely retry the same logical payout.

​
Authentication and signature

Required headers
HeaderRequiredNotes
AuthorizationYesBearer <payout_token> (payout product token only)
X-Custom-SignatureYesBase64 RSA signature. See Signature generation.
Content-TypeYesapplication/json

​
Request body

Top-level fields
FieldTypeRequiredNotes
transactionobjectYesPayout details and idempotency reference.
originatorobjectYesSender details.
recipientobjectYesRecipient details.
callback_urlstringYesHTTPS URL for final status callbacks.
metaobjectNoArbitrary key/value metadata echoed in callbacks.
transaction
FieldTypeRequiredNotes
referencestringYesClient-generated unique reference (idempotency key).
amountintegerYesAmount in major units (e.g., 1000 = 1000 KES).
currencystringYesISO 4217 currency code (e.g., KES, USD).
descriptionstringYesShort narrative for the payout.
service_codestringYesService to use (e.g., MPESAB2C).
timestampstringYesISO 8601 UTC timestamp (must end with Z).
originator
FieldTypeRequiredNotes
msisdnstringYesMSISDN format (e.g., 2547XXXXXXXX).
channelstringYesInitiation channel (e.g., USSD, API).
countrystringYesISO 3166-1 country code (e.g., KE).
namestringYesOriginator name.
purposestringYesReason for the payout.
recipient
FieldTypeRequiredNotes
referencestringYesClient-generated reference for recipient-side tracking.
accountstringYesRecipient account identifier (phone, wallet, bank account).

​
Example request

{
  "transaction": {
    "reference": "TXN213687756272200",
    "amount": 1000,
    "currency": "KES",
    "description": "Vendor payout",
    "service_code": "MPESAB2C",
    "timestamp": "2025-01-21T12:30:10Z"
  },
  "originator": {
    "msisdn": "254708374149",
    "channel": "USSD",
    "country": "KE",
    "name": "Payment",
    "purpose": "Transaction Payment"
  },
  "recipient": {
    "reference": "INVJMA02",
    "account": "254708374149"
  },
  "callback_url": "https://merchant.example.com/callbacks/payout",
  "meta": {
    "note": "This info is returned as part of the callback",
    "agent_id": "AGENT458"
  }
}

​
Example response (accepted)

{
  "code": "100",
  "status": "ACCEPTED",
  "description": "Accepted for processing",
  "data": {
    "amount": 100,
    "transaction_reference": "919938",
    "payment_uuid": "413283551143664292",
    "payment_reference": "351CSICLV0",
    "time_received": "2026-01-07T09:44:43.558023Z"
  }
}

​
Notes

  • Final outcome is delivered via webhook. See Webhooks overview.
  • Errors follow the standard error shape. See Errors.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Custom-Signature
string
required

Base64 RSA signature over: transaction.reference + transaction.amount + originator.country + transaction.service_code

Body

application/json
​
transaction
object
required
​
originator
object
required
​
recipient
object
required
​
callback_url
string<uri>
required

HTTPS URL to receive final status callbacks.

​
meta
object

Arbitrary key-value metadata echoed back in callbacks.

Response

Accepted

​
status
string
required

e.g., 200.100

​
code
string
required

ACCEPTED, REJECTED.

​
description
string
required
​
data
object
required