Cross-border

Overview

KPay isolates funds by country: payments received in Cameroon feed the CMR wallet, those received in Senegal the SEN wallet, etc. — even if the currency is the same (e.g. XAF).

Cross-border operations let you:

• Transfer funds between wallets — move your balance from one country to another (e.g. CMR → GAB), with automatic conversion if currencies differ.
• Cross-country payout — send a Mobile Money withdrawal to country B by debiting the country A wallet, with automatic currency conversion if needed.

Inter-wallet transfer

Moves funds from one country's wallet to another country's wallet, within the same application. If currencies differ (e.g. XAF → XOF), KPay applies the real-time exchange rate.

Endpoint

POST/api/wallets/transfer

Parameters

Example — Same currency (XAF → XAF)

Transfer 50,000 XAF from the Cameroon wallet to the Gabon wallet (both in XAF — no conversion).

{
  "applicationId": "e7c3b4f5-8d9e-4a1b-9c2d-3e4f5a6b7c8d",
  "sourceCountry": "CMR",
  "destinationCountry": "GAB",
  "amount": 50000,
  "description": "Fund transfer CMR to GAB",
  "externalId": "TRF-2026-001"
}

{
  "id": "a1b2c3d4-...",
  "sourceTransaction": {
    "id": "a1b2c3d4-...",
    "reference": "TRF-OUT-ABC123",
    "type": "WALLET_TRANSFER_OUT",
    "amount": 50000,
    "currency": "XAF",
    "country": "CMR"
  },
  "destinationTransaction": {
    "id": "e5f6a7b8-...",
    "reference": "TRF-IN-ABC123",
    "type": "WALLET_TRANSFER_IN",
    "amount": 50000,
    "currency": "XAF",
    "country": "GAB"
  },
  "exchangeRate": 1,
  "description": "Fund transfer CMR to GAB",
  "externalId": "TRF-2026-001",
  "createdAt": "2026-06-23T10:00:00.000Z"
}

Example — Cross-currency (XAF → XOF)

Transfer 100,000 XAF from the Cameroon wallet to the Senegal wallet (XOF). The credited amount is converted at the real-time exchange rate.

{
  "applicationId": "e7c3b4f5-8d9e-4a1b-9c2d-3e4f5a6b7c8d",
  "sourceCountry": "CMR",
  "destinationCountry": "SEN",
  "amount": 100000,
  "description": "Supply Senegal wallet",
  "externalId": "TRF-2026-002"
}

{
  "id": "c3d4e5f6-...",
  "sourceTransaction": {
    "id": "c3d4e5f6-...",
    "reference": "TRF-OUT-DEF456",
    "type": "WALLET_TRANSFER_OUT",
    "amount": 100000,
    "currency": "XAF",
    "country": "CMR"
  },
  "destinationTransaction": {
    "id": "g7h8i9j0-...",
    "reference": "TRF-IN-DEF456",
    "type": "WALLET_TRANSFER_IN",
    "amount": 101530,
    "currency": "XOF",
    "country": "SEN"
  },
  "exchangeRate": 1.0153,
  "description": "Supply Senegal wallet",
  "externalId": "TRF-2026-002",
  "createdAt": "2026-06-23T10:05:00.000Z"
}

Error codes

Cross-country payout

The cross-country payout allows you to send money (Mobile Money) to a beneficiary in country B, while debiting the wallet of country A. This is done via the sourceCountry parameter of the existing withdrawal endpoint.

Endpoint

POST/api/v1/payments/withdraw

sourceCountry parameter

The sourceCountry parameter is the only addition compared to a standard withdrawal. It indicates which wallet to debit, regardless of the beneficiary's country.

Example — Cross-country payout

Send 10,000 XAF to an Orange number in Gabon, debiting the Cameroon wallet (same currency XAF).

const res = await fetch("https://admin.kpay.site/api/v1/payments/withdraw", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "amount": 10000,
  "provider": "ORANGE_GAB",
  "phoneNumber": "237653456789",
  "sourceCountry": "CMR",
  "externalId": "PAYOUT-CROSS-001",
  "description": "Supplier payment Gabon"
}),
});
const data = await res.json();

{
  "id": "wdr_abc789",
  "reference": "KPAY-WD-20260623-ABC789",
  "status": "PENDING",
  "amount": 10000,
  "netAmount": 9500,
  "feeAmount": 500,
  "currency": "XAF",
  "isTest": true,
  "message": "Withdrawal request received. Processing via Mobile Money."
}

Cross-currency payout (automatic conversion)

Debit a CMR (XAF) wallet to pay a beneficiary in Côte d'Ivoire (XOF). The conversion is automatic.

const res = await fetch("https://admin.kpay.site/api/v1/payments/withdraw", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "amount": 50000,
  "provider": "MTN_MOMO_CIV",
  "phoneNumber": "237653456789",
  "sourceCountry": "CMR",
  "externalId": "PAYOUT-CROSS-002",
  "description": "Supplier payment Côte d'Ivoire"
}),
});
const data = await res.json();

{
  "id": "wdr_cross123",
  "reference": "KPAY-WD-20260626-CROSS123",
  "status": "PENDING",
  "amount": 50000,
  "netAmount": 47500,
  "feeAmount": 2500,
  "currency": "XAF",
  "payoutCurrency": "XOF",
  "payoutAmount": 48211.75,
  "exchangeRate": 1.0150,
  "isTest": true,
  "message": "Withdrawal request received. Processing via Mobile Money."
}

Default behavior (without sourceCountry)

Without sourceCountry, the system debits the wallet of the provider's country. A withdrawal to MTN_MOMO_CMR debits the CMR wallet, a withdrawal to ORANGE_GAB debits the GAB wallet. This is the standard behavior.

Usage scenarios

Scenario 1 — Direct payout (same currency)

Your customers pay in Cameroon (XAF). You want to pay a supplier in Gabon (XAF). Same currency → direct payout with sourceCountry.

Wallet CMR (XAF: 100 000)
    │
    └──► POST /api/v1/payments/withdraw
         { provider: "ORANGE_GAB", sourceCountry: "CMR", amount: 10000 }
              │
              └──► Beneficiary receives 9 500 XAF on Orange Gabon

Cross-currency payout (single call)

Debit an XAF wallet to directly pay a beneficiary in a country with a different currency. The conversion is automatic.

Wallet CMR (XAF: 100 000)
    │
    └──► POST /api/v1/payments/withdraw
         { provider: "MTN_MOMO_CIV", sourceCountry: "CMR", amount: 50000 }
              │
              ├── Fees: 2 500 XAF (5%)
              ├── Net: 47 500 XAF
              ├── Rate XAF → XOF: 1.0150
              └──► Beneficiary receives ≈ 48 212 XOF on MTN Côte d'Ivoire

Scenario 3 — Consolidate funds

You receive payments in multiple countries and want to centralize all your funds on a single wallet (e.g. CMR) to simplify management and withdrawals.

POST /api/wallets/transfer { sourceCountry: "GAB", destinationCountry: "CMR", amount: 30000 }
POST /api/wallets/transfer { sourceCountry: "COG", destinationCountry: "CMR", amount: 15000 }

  Wallet CMR ← consolidation of all funds XAF

Supported countries and currencies

Each country has a primary currency. Transfers between countries with the same currency are instant (1:1 rate). Cross-currency transfers use the real-time exchange rate.

Best practices

• Idempotency: always use an externalId for your cross-country transfers and payouts. This prevents duplicates in case of network retry.
• Check the balance: before a transfer, check the source wallet balance via GET /api/wallets/overview (dashboard) or GET /api/v1/payments/balance (API).
• Prefer the direct payout with sourceCountry when the currency is the same. The inter-wallet transfer is only necessary for cross-currency operations.
• Exchange rate: the rate is fixed at the time of transfer and returned in the response. Keep it for your accounting.

Related resources