Transfer (Payout)

Transfer (Payout)

ElementDescription
MethodPOST
Endpoint/v1/payout
Auth✅ Authorization: Basic base64(api_key:api_client)
Idempotence✅ X-Idempotency-Key required to avoid duplicates
Payload Typeapplication/json

Headers

KeyDescriptionRequired
AuthorizationBasic base64(api_key:api_client)✅
X-Idempotency-KeyUUID ensuring request uniqueness✅

Request Body

{
  "reference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "accountId": "merchant_qdadaklwldakld",
  "amount": 300,
  "msisdn": "+2250749929598",
  "country": "CI",
  "customerName": "Habib"
}

Parameter Description

FieldTypeDescriptionRequired
referencestringUnique transfer identifier (merchant-side UUID).✅
accountIdstringMerchant account or sub-account to debit.✅
amountnumberAmount to transfer.✅
msisdnstringBeneficiary's phone number (E.164 format).✅
countrystringCountry ISO code (CI, CM).✅
customerNamestringBeneficiary's name.✅

Response Example

{
  "type": "payout",
  "fee": 6,
  "reference": "mtr_fhscgaywizujwjyymlge1hncaq",
  "phoneNumber": "+2250700000000",
  "customerName": "John Doe",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processed",
  "currency": "XOF",
  "customerReference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "confirmationRequired": false,
  "confirmationStatus": "none",
  "transaction": {
    "reference": "TFHL2A4D3QQC11NW9",
    "status": "completed",
    "processedAt": "2025-08-29T13:39:35.138Z",
    "phoneNumber": "+2250700000000",
    "amount": "300.00",
    "fees": "6.00",
    "chargedAmount": "306.00",
    "currency": "XOF"
  },
  "createdAt": "2025-08-22T02:00:16.026Z"
}

Response Interpretation

FieldDescription
typeTransaction type — here payout (outgoing transfer).
feeService fee amount applied.
referenceAPI-side system reference for the transfer.
phoneNumberBeneficiary's phone number.
customerNameBeneficiary's name.
amountTransfer amount (excluding fees).
chargedAmountTotal amount debited from merchant account (amount + fees).
statusOverall transfer status (processing, processed, expired, etc.).
currencyCurrency used (XOF, USD, EUR, etc.).
customerReferenceOriginal reference provided by the merchant for correlation.
confirmationRequiredIndicates if the beneficiary must confirm before receiving. (Usually false for standard merchant transfers.)
confirmationStatusConfirmation status (useful if beneficiary validation is required).
transactionFinal transfer details executed in the Core System.
createdAtTransfer creation timestamp.

transaction Key

This field contains the final transaction information once the transfer is processed by the Mobile Money processor or internal Core.

FieldDescription
transaction.referenceTechnical reference generated by the processing system.
transaction.statusFinal status (completed, failed, pending).
transaction.processedAtTransfer finalization timestamp.
transaction.phoneNumberCredited account number.
transaction.amountExact credited amount.
transaction.feesFees applied at the processor level.
transaction.chargedAmountTotal amount debited from merchant account.
transaction.currencyCurrency used.

💡 The transaction field becomes available once the transfer is successfully processed.

If it's empty ({}), it means the transfer is still in progress (status = processing).

Transfer Status

GET /v1/payout/{reference}
ElementDescription
MethodGET
Endpoint/v1/payout/{reference}
Auth✅ Authorization required
PayloadNone
DescriptionReturns the complete transfer status corresponding to the provided reference.

Response Example

{
  "type": "payout",
  "fee": 6,
  "reference": "mtr_fhscgaywizujwjyymlge1hncaq",
  "phoneNumber": "+2250700000000",
  "customerName": "John Doe",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processed",
  "currency": "XOF",
  "customerReference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "confirmationRequired": false,
  "confirmationStatus": "none",
  "createdAt": "2025-08-22T02:00:16.026Z",
  "transaction": {},
  "failure": null
}

Response Interpretation

FieldDescription
statusOverall transfer status.
transactionObject containing final information (empty if not yet processed).
failureError details in case of failure (null if successful).

Possible Statuses

StatusDescription
pendingRequest received, awaiting processing.
processingTransfer in progress (contacting Mobile Money operator).
processedTransfer processed on API side, awaiting processor result.
completedTransfer confirmed and credited to beneficiary account.
failedProcessing error (invalid number, insufficient balance, etc.).
reversedFunds returned to merchant following a failure or cancellation.
expiredProcessing deadline exceeded without response.

Obligation

  • Use X-Idempotency-Key to avoid duplicate transfers.
  • Check the status or subscribe to the payout.completed webhook to receive final confirmation.
  • In case of failure, check the failure field for error details (code, message, operator).
  • Do not attempt to manually retry a transfer without verifying failed or expired status.
  • For real-time tracking, use WebSocket or Webhooks (payout.updated, payout.completed).
Payment (Payin)Direct Payment (Mobile money)