Initiate Mobile Money Payout

Initiates a payout from a user's sub-wallet to a mobile money account. The request includes the recipient's phone number, name, mobile money network, and payout amount.

Request

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

Authentication

LedgerBlock uses Bearer Token authentication. Include your API key in the Authorization header.

Parameter	Value	Type
Authorization	`{{api_key}}`	Bearer Token

Headers

Header	Required	Description	Example
`Content-Type`	Yes	Specifies that the request body is JSON.	`application/json`
`x-merchant-ref`	Yes	Unique reference identifying the merchant.	`{{vault:x-merchant-ref}}`

Request Body

Parameter	Required	Description	Example
`user_ref`	Yes	Unique reference identifying the user initiating the payout.	`{{merchant_user_ref}}`
`txn_merchant_ref`	Yes	Unique merchant-generated reference for the transaction.	`DUMMY_LBREF_000001`
`currency`	Yes	Currency used for the mobile money payout.	`KES`
`wallet_type`	Yes	Type of wallet used to fund the payout.	`SUB_WALLET`
`amount`	Yes	Amount to be paid to the recipient.	`100`
`receiver_phone`	Yes	Phone number of the mobile money recipient.	`254700000000`
`receiver_name`	Yes	Name of the recipient.	`Test Recipient`
`network`	Yes	Mobile money network of the recipient.	`AIRTEL`
`narration`	No	Description or purpose of the payout.	`Payment for service`
`notification_url`	Yes	Webhook URL that receives payout status notifications.	`https://example.com/webhooks/payout`

Example Request

{
  "user_ref": "{{merchant_user_ref}}",
  "txn_merchant_ref": "DUMMY_LBREF_000001",
  "currency": "KES",
  "wallet_type": "SUB_WALLET",
  "amount": 100,
  "receiver_phone": "254700000000",
  "receiver_name": "Test Recipient",
  "network": "AIRTEL",
  "narration": "Payment for service",
  "notification_url": "https://example.com/webhooks/payout"
}

Example Response

{
  "status": "success",
  "message": "Payout confirmed. Processing",
  "data": {
    "payment_ref": "dummy-payment-ref-001",
    "txn_merchant_ref": "DUMMY_LBREF_000001",
    "currency": "KES",
    "payment_status": "PENDING",
    "auth_token": "",
    "expires_in_seconds": 0
  }
}

Response

Field	Description
`status`	Indicates whether the request was successful.
`message`	Provides information about the payout result.
`data.payment_ref`	Unique reference assigned to the payout by LedgerBlock.
`data.txn_merchant_ref`	Merchant-generated reference associated with the payout.
`data.currency`	Currency used for the payout.
`data.payment_status`	Current status of the payout. `PENDING` indicates that processing is underway.
`data.auth_token`	Authentication token returned in the response. Empty when no further confirmation token is provided.
`data.expires_in_seconds`	Token validity duration in seconds. `0` indicates that no active confirmation token is provided.

Updated 18 days ago

Did this page help you?