> ## 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.

# Remittances

> Cross-border payouts with KYC fields, signing, acceptance, and delivery confirmation.

Remittances move funds across corridors and require extra KYC fields. The flow mirrors payouts/collections: accept immediately, then finalize via webhook.

***

## Quick flow

Authenticate -> Sign -> Send remittance -> Receive acceptance -> Receive webhook -> Reconcile (optional status check).

***

## Prerequisites

* Product-scoped Bearer token from [Authentication API](/api-reference/auth/auth-token).
* RSA 2048 key pair registered with Waftpay. See [Signature generation](/api-reference/signatures/signature-generate).
* Correct base URL for your environment. See [Environments](/environments).

***

## Endpoint

**POST** `/payments/api/v1/remittance`

**Required headers**

```http theme={null}
Authorization: Bearer <access_token>
Content-Type: application/json
X-Custom-Signature: <base64-signature>
```

**Idempotency**: reuse the same `transaction.reference` for retries of the same logical remittance.

***

## Request body (example — 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"
  }
}
```

### 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"
  }
}
```

**Notes**

* `transaction.timestamp` for remittance uses `YYYY-MM-DD HH:mm:ss` (no timezone suffix).
* KYC fields are required per corridor. At minimum, the originator needs `nationality`, `address`, `msisdn`, `country`, and `purpose`; the recipient needs `address`, `country`, `relationship`, `account_type`, and `account`. Provide name, DOB, and ID details where available.
* Use `bank_code` for `BANK` recipients. For Corporate parties, supply `company_name` and `company_registration`.

***

## Acceptance response (immediate)

The acceptance response uses the same envelope as payouts. See [Initiate remittance API](/api-reference/remittance/remittance-initiate).

***

## Webhook (final outcome)

We POST to your `callback_url` when the remittance completes. See [Webhook payload](/pages/webhooks/payload).

***

## Status checks (optional)

If a webhook is delayed or missing, query status using [Check remittance status](/api-reference/remittance/remittance-status) or [Status checks](/pages/guides/status-checks).

***

## Common issues

* **Signature mismatch**: ensure the string-to-sign matches the payload exactly. See [Signature generation](/api-reference/signatures/signature-generate).
* **Wrong token**: use a remittance-scoped Bearer token.
* **Timestamp format**: remittance uses `YYYY-MM-DD HH:mm:ss`.

***

## Related links

* [Initiate remittance API](/api-reference/remittance/remittance-initiate)
* [Check remittance status](/api-reference/remittance/remittance-status)
* [Webhooks overview](/pages/webhooks/overview)
* [Errors](/errors)