Subwallet to Mobile Money

Transfers funds from a user's SubWallet to an external mobile money account.

Request

Method: POST

Endpoint:

{{base_url}}/api/v1/payout/wallet-mobilemoney

Authentication & Headers

Header	Type	Required	Description
`Authorization`	String	Yes	`Bearer <token>` — your activated authentication token.
`x-merchant-ref`	String	Yes	Your unique merchant reference.
`Content-Type`	String	Yes	Must be set to `application/json`.

Example Request

curl --location -g '{{base_url}}/api/v1/payout/wallet-mobilemoney' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-merchant-ref: MERCHANT-REF-001' \
--data '{
  "user_ref": "USER-REF-001",
  "txn_merchant_ref": "TXN-REF-001",
  "currency": "KES",
  "wallet_type": "SUB_WALLET",
  "amount": 100,
  "receiver_phone": "254700000000",
  "receiver_name": "John Doe",
  "network": "AIRTEL",
  "narration": "Payment for service",
  "notification_url": "https://example.com/webhook"
}'

Request Body

{
  "user_ref": "USER-REF-001",
  "txn_merchant_ref": "TXN-REF-001",
  "currency": "KES",
  "wallet_type": "SUB_WALLET",
  "amount": 100,
  "receiver_phone": "254700000000",
  "receiver_name": "John Doe",
  "network": "AIRTEL",
  "narration": "Payment for service",
  "notification_url": "https://example.com/webhook"
}

Request Fields

Field	Type	Required	Description
`user_ref`	String	Yes	Unique reference identifying the user whose SubWallet will be debited.
`txn_merchant_ref`	String	Yes	Unique merchant reference for the payout transaction.
`currency`	String	Yes	Currency of the mobile money payout, e.g. `KES`.
`wallet_type`	String	Yes	Specifies the source wallet. For SubWallet payouts, use `SUB_WALLET`.
`amount`	Number	Yes	Amount to be transferred to the mobile money account.
`receiver_phone`	String	Yes	Phone number associated with the recipient's mobile money account.
`receiver_name`	String	Yes	Name of the mobile money recipient.
`network`	String	Yes	Mobile money network of the recipient, e.g. `AIRTEL`.
`narration`	String	Yes	Description or purpose of the transaction.
`notification_url`	String	No	URL where LedgerBlock can send transaction status notifications.

Transfer Flow

User SubWallet → Select Mobile Money → Provide Recipient Details → Authorize Transaction → Transfer Processing → Mobile Money Account Credited

Note: The supported currency, mobile money network, and recipient requirements depend on the destination market and available payout rail.