Initiate Wallet-to-CAD Payout

Initiates a payout in Canadian dollars (CAD) from a user's wallet. The request includes the recipient's details and payout amount. The payout must be confirmed using the user's wallet PIN before processing can continue.

Request

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

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_CAD_PAYOUT_001`
`amount`	Yes	Amount to be paid in CAD.	`2.50`
`email`	Yes	Recipient's email address.	`[email protected]`
`first_name`	Yes	Recipient's first name.	`Test`
`last_name`	Yes	Recipient's last name.	`Recipient`
`note`	No	Optional note describing the payout.	`Payout note`
`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`

Example Request

{
  "user_ref": "{{merchant_user_ref}}",
  "txn_merchant_ref": "DUMMY_CAD_PAYOUT_001",
  "amount": 2.50,
  "email": "[email protected]",
  "first_name": "Test",
  "last_name": "Recipient",
  "note": "Payout note",
  "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_CAD_PAYOUT_001",
    "currency": "CAD",
    "payment_status": "AWAITING_CONFIRMATION",
    "auth_token": "{{auth_token}}",
    "expires_in_seconds": 600
  }
}

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. The response is expected to return `CAD`.
`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

Use the returned auth_token and the user's wallet PIN to confirm the payout through the corresponding CAD payout confirmation endpoint.

Updated 19 days ago

Did this page help you?