> ## Documentation Index > Fetch the complete documentation index at: https://docs.waftpay.io/llms.txt > Use this file to discover all available pages before exploring further. # Initiate Remittance > Create a remittance request. ## 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 ` | | `X-Custom-Signature` | Yes | Base64 RSA signature. See [Signature generation](/api-reference/signatures/signature-generate). | | `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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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](/pages/webhooks/overview). * Errors follow the standard error shape. See [Errors](/errors). ## OpenAPI ````yaml POST /payments/api/v1/remittance openapi: 3.1.0 info: title: Waftpay Payments API description: >- Process payments, collect funds, and remit payouts with Waftpay. Includes Authentication Token, idempotency, webhooks, and sandbox support. license: name: MIT version: 1.0.0 servers: - url: https://dev.waftpay.io description: Sandbox (dev) security: - bearerAuth: [] tags: - name: Authentication description: Obtain and manage access tokens - name: Payments description: Charge a customer and track status - name: Collections description: Customer-initiated payments and hosted checkouts - name: Checkout description: >- Hosted checkout flow for customer payments. Flow: 1. Ensure the Collections service is enabled for your account. 2. Use `consumer_key` and `consumer_secret` to generate a Bearer token via **Get Authentication Token**. 3. Cache the token and refresh only on expiry. 4. Call **Create Checkout Request** with customer details, amount, and redirect URLs. 5. Use the returned `checkout_url` for redirect or iframe. 6. The `callback_url` receives a payload matching the `CheckoutCallback` schema. - name: Remittance description: Send payouts to mobile wallets and bank accounts - name: Webhooks description: Receive asynchronous notifications - name: Utilities description: Common utilities (idempotency, health) paths: /payments/api/v1/remittance: post: tags: - Remittance summary: Initiate Remittance description: >- Create a remittance request. Provide a unique `transaction.reference` for idempotency. Uses the same Bearer authentication and `X-Custom-Signature` convention as payouts/collections. operationId: initiateRemittance parameters: - $ref: '#/components/parameters/XCustomSignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRemittanceRequestV1' examples: default: summary: Individual originator, BANK recipient value: 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 corporate_momo: summary: Corporate originator, MOMO recipient value: transaction: reference: TXN998877 amount: 5000 currency: KES description: Supplier payment service_code: PESALINK_REM timestamp: '2025-09-15 12:45:30' 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 responses: '201': description: Accepted content: application/json: schema: $ref: '#/components/schemas/PayoutInitiationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: parameters: XCustomSignature: name: X-Custom-Signature in: header required: true schema: type: string description: >- Base64 RSA signature over: transaction.reference + transaction.amount + originator.country + transaction.service_code schemas: CreateRemittanceRequestV1: type: object required: - transaction - originator - recipient - callback_url properties: transaction: type: object required: - reference - amount - currency - description - service_code - timestamp properties: reference: type: string description: >- Client-generated unique reference (idempotency key). Reuse to safely retry. amount: type: integer description: Amount in major units (e.g., 100 = 100 KES). currency: type: string description: ISO 4217 currency code (e.g., KES, USD). description: type: string description: Short narrative for the remittance. service_code: type: string description: Service to consume (corridor/payout rail code). timestamp: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ description: >- Timestamp in 'YYYY-MM-DD HH:mm:ss' as provided by client (assumed UTC unless configured). originator: type: object required: - nationality - address - msisdn - country - purpose properties: originator_type: type: string description: Originator type. Either 'Individual' or 'Corporate'. first_name: type: string description: Originator first name. other_names: type: string description: Originator other/last names. dob: type: string description: Date of birth (YYYY-MM-DD). nationality: type: string description: Originator nationality (e.g., UK). id_type: type: string description: Identification type (e.g., Passport, ID, DL). id_number: type: string description: >- Identification number (e.g., Passport number, ID number, DL number). id_expiry_date: type: string description: Identification expiry date (YYYY-MM-DD). address: type: string description: Originator address. company_name: type: string description: Company name (for Corporate originators). company_registration: type: string description: Company registration number (for Corporate originators). service_provider: type: string description: >- Sending provider name as used in your corridor (e.g., TELCOM-UK). msisdn: type: string description: Originator phone number in MSISDN format (e.g., 2547XXXXXXXX). channel: type: string description: Channel used to initiate the remittance (e.g., USSD, API). country: type: string description: >- Country code; tenant may use ISO-2 (KE) or ISO-3 (KEN). Use what your account is configured for. purpose: type: string description: Purpose of sending the funds. recipient: type: object required: - address - country - relationship - account_type - account properties: recipient_type: type: string description: Recipient type. Either 'Individual' or 'Corporate'. first_name: type: string description: Recipient first name. other_names: type: string description: Recipient other/last names. id_type: type: string description: Identification type (e.g., Passport, ID, DL). id_number: type: string description: Identification number. id_expiry_date: type: string description: Identification expiry date (YYYY-MM-DD). dob: type: string description: Date of birth (YYYY-MM-DD). address: type: string description: Recipient address. company_name: type: string description: Company name (for Corporate recipients). company_registration: type: string description: Company registration number (for Corporate recipients). msisdn: type: string description: >- Recipient phone number in MSISDN format. If provided, cannot be empty. country: type: string description: Recipient country code. nationality: type: string description: Recipient nationality. relationship: type: string description: Recipient's relationship to the originator. reference: type: string description: Client-generated unique reference for recipient context. account_type: type: string enum: - MOMO - BANK description: Recipient account type. Either 'MOMO' or 'BANK'. account: type: string description: >- Recipient account identifier (phone, wallet, bank account, etc.). bank_code: type: string description: Bank code (for 'BANK' account types). callback_url: type: string format: uri description: HTTPS URL to receive final status callbacks. meta: type: object description: Arbitrary key-value metadata echoed back in callbacks. additionalProperties: true examples: - 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 PayoutInitiationResponse: type: object required: - status - code - description - data properties: status: type: string description: e.g., 200.100 code: type: string description: ACCEPTED, REJECTED. description: type: string data: type: object required: - amount - transaction_reference - payment_uuid - payment_reference - time_received properties: amount: type: number transaction_reference: type: string payment_uuid: type: string description: UUID or numeric string identifier. payment_reference: type: string time_received: type: string format: date-time description: ISO 8601 UTC timestamp. **Always ends with 'Z'**. additionalProperties: true examples: accepted: summary: Accepted for processing value: status: '200.100' code: ACCEPTED description: Accepted for processing data: {} duplicateIgnored: summary: Duplicate ignored value: status: '200.100' code: REJECTED description: Duplicate payout ignored data: {} rejected: summary: Rejected value: status: '400.100' code: REJECTED description: Invalid recipient account number data: null Error: type: object required: - error - message properties: error: type: string description: Machine readable error code message: type: string description: Human readable message param: type: string request_id: type: string WaftpayErrorEnvelope: type: object required: - code - status - description properties: code: type: string description: >- Application code. Can be a top-level code (e.g., 400.600) or a granular code (e.g., 404.001.000). status: type: string description: >- Semantic status, e.g., REJECTED, FAILED, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, ACCEPTED. description: type: string description: Human-readable description. data: type: object description: Additional details (may be empty). additionalProperties: true nullable: true examples: notFoundGranular: summary: 404 with granular code value: code: 404.001.000 status: REJECTED description: Requested resource not found data: {} validationFailed: summary: 400 validation failed value: code: '400.100' status: REJECTED description: Validation failed data: field_errors: - field: recipient.account message: Invalid account unauthorized: summary: 401 failed authentication value: code: '400.200' status: REJECTED description: Failed Authentication data: null forbidden: summary: 403 failed authorization value: code: '403.300' status: REJECTED description: Failed Authorization data: null internal: summary: 500 internal server error value: code: '400.500' status: FAILED description: Internal server error data: null responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid token content: application/json: schema: $ref: '#/components/schemas/WaftpayErrorEnvelope' examples: unauthorized: value: code: 400.001.100 status: REJECTED description: Invalid or expired token data: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````