Skip to main content
POST
/
payments-api-service
/
v1
/
remittance
Initiate Remittance
curl --request POST \
  --url https://sandbox.waftpay.io/api/payments-api-service/v1/remittance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Custom-Signature: <x-custom-signature>' \
  --data '
{
  "transaction": {
    "reference": "TXN123654573",
    "amount": 100,
    "currency": "KES",
    "description": "Test",
    "service_code": "ewqeqw",
    "timestamp": "2025-01-21 12:30:10"
  },
  "originator": {
    "msisdn": "254722111999",
    "channel": "Test",
    "country": "KEN",
    "Service_provider": "TELCOM-UK",
    "name": "John Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "Passport",
    "id_number": "PSA010101",
    "purpose": "No purpose"
  },
  "recipient": {
    "reference": "Test",
    "account": "Test",
    "name": "John Doe Init"
  },
  "callback_url": "https://www.google.com",
  "meta": {
    "note": "Test",
    "agent_id": "Test"
  }
}
'
{
  "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 Remittance API to send cross-border payouts. Remittances 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 remittance.

​
Authentication and signature

Required headers
HeaderRequiredNotes
AuthorizationYesBearer <remittance_token>
X-Custom-SignatureYesBase64 RSA signature. See Signature generation.
Content-TypeYesapplication/json
String to sign (no separators) 
transaction.reference + transaction.amount + originator.country + transaction.service_code
Use the exact string values you send in the JSON (including casing).

​
Request body

Top-level fields
FieldTypeRequiredNotes
transactionobjectYesRemittance 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., 100 = 100 KES).
currencystringYesISO 4217 currency code (e.g., KES, USD).
descriptionstringYesShort narrative for the remittance.
service_codestringYesCorridor/payout rail code.
timestampstringYesFormat: YYYY-MM-DD HH:mm:ss.
originator
FieldTypeRequiredNotes
msisdnstringYesMSISDN format (e.g., 2547XXXXXXXX).
channelstringYesInitiation channel (e.g., USSD, API).
countrystringYesCountry code (ISO-2 or ISO-3 as configured on your account).
Service_providerstringYesSending provider name (corridor-specific).
namestringYesOriginator full name.
dobstringYesDate of birth (YYYY-MM-DD).
nationalitystringYesOriginator nationality (e.g., UK).
id_typestringYesIdentification type (e.g., Passport).
id_numberstringYesIdentification number.
purposestringYesPurpose of sending the funds.
recipient
FieldTypeRequiredNotes
referencestringYesClient-generated reference for recipient context.
accountstringYesRecipient account identifier.
namestringYesRecipient full name.

​
Example request

{
  "transaction": {
    "reference": "TXN123654573",
    "amount": 100,
    "currency": "KES",
    "description": "Test",
    "service_code": "ewqeqw",
    "timestamp": "2025-01-21 12:30:10"
  },
  "originator": {
    "msisdn": "254722111999",
    "channel": "Test",
    "country": "KEN",
    "Service_provider": "TELCOM-UK",
    "name": "John Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "Passport",
    "id_number": "PSA010101",
    "purpose": "No purpose"
  },
  "recipient": {
    "reference": "Test",
    "account": "Test",
    "name": "John Doe Init"
  },
  "callback_url": "https://www.google.com",
  "meta": {
    "note": "Test",
    "agent_id": "Test"
  }
}

​
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