Search documentation

Search across BlockBee docs, API endpoints, webhooks and guides.

Process Payout by ID

View as Markdown

Use this endpoint to process a specific Payout using its ID.

Notes:

  • Payouts in error or expired status are retried by calling this endpoint again with the same payout_id. Previous attempts are verified on-chain before anything is re-sent, so a retry can never double-pay.
  • Safe to retry on timeouts: re-submitting a payout that is already in flight returns success without sending funds twice.
  • Throws an error if the payout was already sent (done) or was rejected.
  • The payout moves to done only after the settlement transaction confirms on-chain. Track it by polling Get Payout Status or via your payout webhook.

Method: POST

Path: https://api.blockbee.io/payout/process/

Parameters

Query Parameters

apikeystring•Required

API Key provided by BlockBee's Dashboard. Unsure how to get yours? Check this tutorial.

Note: The API key can also be sent as a header named apikey.

Request Body

This endpoint requires a request body with the payout_id.

Note: The request Content-Type header must be set to application/x-www-form-urlencoded.

payout_idstring•Required

The ID of the payout you want to process.

Example:{payout_id: 7f839bdd-5acd-4ce3-984d-1be8357b642d}

Returns

Returns a success message with payout information. Returns an error if the payout has already been processed or if the payout_id is invalid.

statusstring

Status of the request.

payout_infoobject

Contains detailed information about the payout request.

idstring

Unique identifier for the payout request.

statusstring

Current status of the payout request. Can be created, processing, done, rejected, expired, or error.

display_statusstring

Current verbose status of the payout request. Can be Created, Pending Payment, Done, Rejected, Expired, or Error.

fromstring

Source address for the payout, if applicable.

requestsobject

A mapping of destination addresses to the amount requested for each.

total_requestedstring

Total cryptocurrency amount requested.

total_with_feestring

Total cryptocurrency amount including the fee.

errorstring

The error message. This field is always present but is empty unless the payout status is error or expired.

blockchain_feestring

The fee paid to the blockchain for the transaction.

feestring

Fee associated with the transaction.

coinstring

Cryptocurrency ticker for the transaction.

txidstring

Transaction ID, available once the payout is fulfilled.

timestampstring

Timestamp when the payout was created.

webhook_logsarray

Delivery log of your payout webhook for this payout. Empty if no webhook URL is configured.

queuedboolean

Indicates whether the payout was accepted for signing and broadcast. true is not confirmation; wait for done.

Errors

HTTP 400 with { "status": "error", "error": "<message>" }:

ErrorCause
Payout not foundUnknown payout_id for this API key.
This payout has already been sent!The payout is done, or already has a settlement txid.
This payout has been rejected!The payout is rejected.
This endpoint is for API key v2 onlyThe profile has no API Key V2.
API key incorrectThe key failed TSS verification.
No payout dataThe payout has no valid outputs; it is rejected.

Failed attempts also surface through the payout status. An error payout may carry reasons such as Not enough balance, Settlement transaction reverted, or Settlement transaction invalidated on-chain, safe to retry (the last means BlockBee proactively invalidated a dead transaction and the payout can be retried immediately).