Initiate Remittance - Waftpay Developer Docs

curl --request POST \
  --url https://dev.waftpay.io/payments/api/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": {
    "originator_type": "Individual",
    "first_name": "John",
    "other_names": "Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "National ID",
    "id_number": "PSA010101",
    "id_expiry_date": "2030-01-01",
    "address": "10 Downing Street, London",
    "service_provider": "TELCOM-UK",
    "msisdn": "256722111999",
    "channel": "USSD",
    "country": "KEN",
    "purpose": "Family support"
  },
  "recipient": {
    "recipient_type": "Individual",
    "first_name": "Ralph",
    "other_names": "Doe",
    "id_type": "National ID",
    "id_number": "RCP55512",
    "dob": "1990-05-20",
    "address": "123 Riverside Drive, Nairobi",
    "msisdn": "254712345678",
    "country": "KEN",
    "nationality": "KE",
    "relationship": "Sibling",
    "reference": "Test",
    "account_type": "BANK",
    "account": "9382947489",
    "bank_code": "0002"
  },
  "callback_url": "https://webhook",
  "meta": {
    "note": "QA 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"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "param": "<string>",
  "request_id": "<string>"
}

{
  "code": "400.001.100",
  "status": "REJECTED",
  "description": "Invalid or expired token",
  "data": {}
}

POST

payments

api

remittance

curl --request POST \
  --url https://dev.waftpay.io/payments/api/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": {
    "originator_type": "Individual",
    "first_name": "John",
    "other_names": "Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "National ID",
    "id_number": "PSA010101",
    "id_expiry_date": "2030-01-01",
    "address": "10 Downing Street, London",
    "service_provider": "TELCOM-UK",
    "msisdn": "256722111999",
    "channel": "USSD",
    "country": "KEN",
    "purpose": "Family support"
  },
  "recipient": {
    "recipient_type": "Individual",
    "first_name": "Ralph",
    "other_names": "Doe",
    "id_type": "National ID",
    "id_number": "RCP55512",
    "dob": "1990-05-20",
    "address": "123 Riverside Drive, Nairobi",
    "msisdn": "254712345678",
    "country": "KEN",
    "nationality": "KE",
    "relationship": "Sibling",
    "reference": "Test",
    "account_type": "BANK",
    "account": "9382947489",
    "bank_code": "0002"
  },
  "callback_url": "https://webhook",
  "meta": {
    "note": "QA 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"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "param": "<string>",
  "request_id": "<string>"
}

{
  "code": "400.001.100",
  "status": "REJECTED",
  "description": "Invalid or expired token",
  "data": {}
}

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

Header	Required	Notes
`Authorization`	Yes	`Bearer <remittance_token>`
`X-Custom-Signature`	Yes	Base64 RSA signature. See Signature generation.
`Content-Type`	Yes	`application/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

Field	Type	Required	Notes
`transaction`	object	Yes	Remittance details and idempotency reference.
`originator`	object	Yes	Sender details.
`recipient`	object	Yes	Recipient details.
`callback_url`	string	Yes	HTTPS URL for final status callbacks.
`meta`	object	No	Arbitrary key/value metadata echoed in callbacks.

transaction

Field	Type	Required	Notes
`reference`	string	Yes	Client-generated unique reference (idempotency key).
`amount`	integer	Yes	Amount in major units (e.g., 100 = 100 KES).
`currency`	string	Yes	ISO 4217 currency code (e.g., KES, USD).
`description`	string	Yes	Short narrative for the remittance.
`service_code`	string	Yes	Corridor/payout rail code.
`timestamp`	string	Yes	Format: `YYYY-MM-DD HH:mm:ss`.

originator

Field	Type	Required	Notes
`originator_type`	string	No	`Individual` or `Corporate`.
`first_name`	string	No	Originator first name.
`other_names`	string	No	Originator other/last names.
`dob`	string	No	Date of birth (YYYY-MM-DD).
`nationality`	string	Yes	Originator nationality (e.g., UK).
`id_type`	string	No	Identification type (e.g., Passport).
`id_number`	string	No	Identification number.
`id_expiry_date`	string	No	Identification expiry date (YYYY-MM-DD).
`address`	string	Yes	Originator address.
`company_name`	string	No	Company name (for Corporate originators).
`company_registration`	string	No	Company registration number (for Corporate originators).
`service_provider`	string	No	Sending provider name (corridor-specific).
`msisdn`	string	Yes	MSISDN format (e.g., 2547XXXXXXXX).
`channel`	string	No	Initiation channel (e.g., USSD, API).
`country`	string	Yes	Country code (ISO-2 or ISO-3 as configured on your account).
`purpose`	string	Yes	Purpose of sending the funds.

recipient

Field	Type	Required	Notes
`recipient_type`	string	No	`Individual` or `Corporate`.
`first_name`	string	No	Recipient first name.
`other_names`	string	No	Recipient other/last names.
`id_type`	string	No	Identification type (e.g., Passport).
`id_number`	string	No	Identification number.
`id_expiry_date`	string	No	Identification expiry date (YYYY-MM-DD).
`dob`	string	No	Date of birth (YYYY-MM-DD).
`address`	string	Yes	Recipient address.
`company_name`	string	No	Company name (for Corporate recipients).
`company_registration`	string	No	Company registration number (for Corporate recipients).
`msisdn`	string	No	MSISDN format. If provided, cannot be empty.
`country`	string	Yes	Country code.
`nationality`	string	No	Recipient nationality.
`relationship`	string	Yes	Recipient’s relationship to the originator.
`reference`	string	No	Client-generated reference for recipient context.
`account_type`	string	Yes	`MOMO` or `BANK`.
`account`	string	Yes	Recipient account identifier.
`bank_code`	string	No	Bank code (for `BANK` account types).

Example request (Individual originator, BANK recipient)

{
  "transaction": {
    "reference": "{{remittance_transaction_ref}}",
    "amount": 1000,
    "currency": "KES",
    "description": "QA Tests",
    "service_code": "PESALINK_REM",
    "timestamp": "2025-09-15T12:45:30.123Z"
  },
  "originator": {
    "originator_type": "Individual",
    "first_name": "John",
    "other_names": "Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "National ID",
    "id_number": "PSA010101",
    "id_expiry_date": "2030-01-01",
    "address": "10 Downing Street, London",
    "service_provider": "TELCOM-UK",
    "msisdn": "256722111999",
    "channel": "USSD",
    "country": "KEN",
    "purpose": "Family support"
  },
  "recipient": {
    "recipient_type": "Individual",
    "first_name": "Ralph",
    "other_names": "Doe",
    "id_type": "National ID",
    "id_number": "RCP55512",
    "dob": "1990-05-20",
    "address": "123 Riverside Drive, Nairobi",
    "msisdn": "254712345678",
    "country": "KEN",
    "nationality": "KE",
    "relationship": "Sibling",
    "reference": "Test",
    "account_type": "BANK",
    "account": "9382947489",
    "bank_code": "0002"
  },
  "callback_url": "https://webhook",
  "meta": {
    "note": "QA Test",
    "agent_id": "Test"
  }
}

Example request (Corporate originator, MOMO recipient)

{
  "transaction": {
    "reference": "{{remittance_transaction_ref}}",
    "amount": 5000,
    "currency": "KES",
    "description": "Supplier payment",
    "service_code": "PESALINK_REM",
    "timestamp": "2025-09-15T12:45:30.123Z"
  },
  "originator": {
    "originator_type": "Corporate",
    "company_name": "Acme Trading Ltd",
    "company_registration": "UK-7782211",
    "nationality": "UK",
    "address": "10 Downing Street, London",
    "service_provider": "TELCOM-UK",
    "msisdn": "256722111999",
    "channel": "API",
    "country": "KEN",
    "purpose": "Supplier payment"
  },
  "recipient": {
    "recipient_type": "Individual",
    "first_name": "Ralph",
    "other_names": "Doe",
    "address": "123 Riverside Drive, Nairobi",
    "msisdn": "254712345678",
    "country": "KEN",
    "nationality": "KE",
    "relationship": "Supplier",
    "reference": "INV-2025-091",
    "account_type": "MOMO",
    "account": "254712345678"
  },
  "callback_url": "https://webhook",
  "meta": {
    "note": "QA 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

Show child attributes

originator

object

required

Show child attributes

recipient

object

required

Show child attributes

callback_url

string<uri>

required

HTTPS URL to receive final status callbacks.

Response

Accepted

status

string

required

e.g., 200.100

code

string

required

ACCEPTED, REJECTED.

description

string

required

data

object

required

Show child attributes

Create Checkout Request Check Remittance Status

​Overview

​Authentication and signature

​Request body

​Example request (Individual originator, BANK recipient)

​Example request (Corporate originator, MOMO recipient)

​Example response (accepted)

​Notes

Authorizations

Headers

Body

Response

Overview

Authentication and signature

Request body

Example request (Individual originator, BANK recipient)

Example request (Corporate originator, MOMO recipient)

Example response (accepted)

Notes