Initiate Wallet-to-Bank Payout

Initiates a payout from a user's sub-wallet to a bank account. The payout must be confirmed using the user's wallet PIN before processing can continue.

Request

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

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

Example Request

{
  "user_ref": "{{merchant_user_ref}}",
  "currency": "NGN",
  "wallet_type": "SUB_WALLET",
  "txn_merchant_ref": "DUMMY_LBREF_000001",
  "amount": 500,
  "account_no": "0123456789",
  "bank_code": "000001",
  "meta_data": {},
  "notification_url": "https://example.com/webhooks/payout"
}

Example Response

{
  "status": "success",
  "message": "Payout initialized. Confirm with your wallet PIN to complete it",
  "data": {
    "payment_ref": "dummy-payment-ref-001",
    "txn_merchant_ref": "DUMMY_LBREF_000001",
    "currency": "NGN",
    "payment_status": "AWAITING_CONFIRMATION",
    "auth_token": "{{auth_token}}",
    "expires_in_seconds": 600
  }
}

Request Body

Parameter	Required	Description	Example
`user_ref`	Yes	Unique reference identifying the user initiating the payout.	`{{merchant_user_ref}}`
`currency`	Yes	Currency of the payout.	`NGN`
`wallet_type`	Yes	Type of wallet used to fund the payout.	`SUB_WALLET`
`txn_merchant_ref`	Yes	Unique merchant-generated reference for the transaction.	`DUMMY_LBREF_000001`
`amount`	Yes	Amount to be paid to the bank account.	`500`
`account_no`	Yes	Recipient's bank account number.	`0123456789`
`bank_code`	Yes	Code identifying the recipient's bank.	`000001`
`meta_data`	No	Optional additional information associated with the payout.	`{}`
`notification_url`	Yes	Webhook URL that receives payout status notifications.	`https://example.com/webhooks/payout`

Response

Field	Description
`status`	Indicates whether the payout initiation request was successful.
`message`	Provides information about the result of the request.
`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. `AWAITING_CONFIRMATION` means the payout requires confirmation.
`data.auth_token`	Temporary token required to confirm the payout.
`data.expires_in_seconds`	Time in seconds before the authentication token expires.

Next Step

After initiating the payout, use the returned auth_token and the user's wallet PIN to confirm the transaction through the wallet-to-bank payout confirmation endpoint.

Add the PIN confirmation endpointClarify the authentication header

Updated 18 days ago

Did this page help you?