Initiate Crypto Payout

Initiates a cryptocurrency payout from a LedgerBlock wallet to an external crypto wallet address. The request specifies the cryptocurrency, blockchain network, source wallet type, amount, and destination wallet address.

Once the payout is successfully initialized, LedgerBlock returns an auth token that is required to confirm the payout using the user's wallet PIN. The token expires after the specified validity period.

Endpoint

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

Authentication

LedgerBlock uses Bearer token authentication. Include your API key in the Authorization header for authenticated requests.

Header	Required	Description	Example
`Authorization`	Yes	Authenticates the request using your API key.	`Bearer {{api_key}}`

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	Type	Required	Description	Example
`user_ref`	string	Yes	Reference of the user initiating the payout.	`USR_784521`
`currency`	string	Yes	Cryptocurrency and token network identifier.	`USDT:POL`
`chain`	string	Yes	Blockchain network used for the payout.	`POL`
`wallet_type`	string	Yes	Type of wallet from which the payout is made.	`SUB_WALLET`
`txn_merchant_ref`	string	Yes	Unique merchant reference for the payout transaction.	`CRP_PAY_001245`
`amount`	number	Yes	Amount of cryptocurrency to transfer.	`5`
`to_wallet_address`	string	Yes	Destination cryptocurrency wallet address.	`0x1234abcd5678ef901234abcd5678ef901234abcd`
`notification_url`	string	No	URL to receive transaction notifications.	`https://example.com/webhook`

Example Request

{
  "user_ref": "USR_784521",
  "currency": "USDT:POL",
  "chain": "POL",
  "wallet_type": "SUB_WALLET",
  "txn_merchant_ref": "CRP_PAY_001245",
  "amount": 5,
  "to_wallet_address": "0x1234abcd5678ef901234abcd5678ef901234abcd",
  "notification_url": "https://example.com/webhook"
}

Example Response

{
  "status": "success",
  "message": "Payout initialized. Confirm with your wallet PIN to complete it",
  "data": {
    "payment_ref": "d92f1a63-8b74-4c21-9e56-2f8a7b6c1234",
    "txn_merchant_ref": "CRP_PAY_001245",
    "currency": "USDT:POL",
    "chain": "POL",
    "payment_status": "AWAITING_CONFIRMATION",
    "auth_token": "a81c7e42f9b35d60e2148a76c593d0e7",
    "expires_in_seconds": 600
  }
}

Response

Field	Type	Description
`status`	string	Indicates whether the payout was successfully initialized.
`message`	string	Provides the result of the payout initialization.
`data`	object	Contains the payout details and authorization information.
`data.payment_ref`	string	Unique payment reference generated for the payout.
`data.txn_merchant_ref`	string	Merchant reference associated with the payout.
`data.currency`	string	Cryptocurrency and token network identifier.
`data.chain`	string	Blockchain network used for the payout.
`data.payment_status`	string	Current status of the payout. `AWAITING_CONFIRMATION` indicates that confirmation is required.
`data.auth_token`	string	Temporary authorization token required to confirm the payout.
`data.expires_in_seconds`	integer	Time in seconds before the authorization token expires.

Next Step: Use the returned auth_token in the payout confirmation request with the user's wallet PIN to complete the payout.