Pay Out integration

A Pay Out sends funds from your available balance to a recipient. The amount plus fees is reserved straight away, so a payout can never spend money twice. Live payouts may need approval by our team before they are sent to the provider.

Request a payout

POST /payouts · scope payouts:write · requires an Idempotency-Key header

Field	Type	Description
`amount` required	string	Amount the recipient should receive, as a decimal string.
`currency` required	string	Currency code. Paid from your balance in the same currency; currencies are never converted.
`reference` required	string	Your unique ID for this payout (1–64 characters: letters, digits, `_`, `-`).
`destination.type` required	string	`crypto_address`, `binance_id` or `email`. Which types are allowed depends on the provider (see below).
`destination.value` required	string	The wallet address, numeric Binance ID or email address.
`destination.memo`	string	Memo or destination tag, for networks that need one (up to 64 characters).
`network`	string	Required for `crypto_address` payouts through Cryptomus, for example `tron`.
`provider`	string	`cryptomus` or `binance_pay`. Omit to pick the first enabled provider that supports the currency and destination type.
`description`	string	Up to 255 characters.
`metadata`	object	Up to 20 string values.

Destinations per provider

Provider	Destination types	Notes
Cryptomus	`crypto_address`	Sent on-chain from the platform's Cryptomus wallet. `network` is required.
Binance Pay	`binance_id`, `email`	Internal Binance transfer to a Binance account. Binance Pay cannot pay out to external blockchain addresses.

Example

curl -X POST https://gatway.hunario.com/api/v1/payouts \
  -H "Authorization: Bearer $GATEWAY_SECRET_KEY" \
  -H "Idempotency-Key: withdrawal-778" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "currency": "USDT",
    "network": "tron",
    "reference": "withdrawal-778",
    "destination": { "type": "crypto_address", "value": "TQ5n...your-wallet" }
  }'

Response 201

{
  "data": {
    "id": "po_01j9x5...",
    "object": "payout",
    "status": "under_review",
    "provider": "cryptomus",
    "reference": "withdrawal-778",
    "amount": "250.00000000",
    "currency": "USDT",
    "network": "tron",
    "destination": { "type": "crypto_address", "value": "TQ5n...", "memo": null },
    "service_fee": "2.50000000",
    "network_fee": "1.00000000",
    "total_debit": "253.50000000",
    "tx_hash": null,
    "failure_reason": null,
    "rejection_reason": null
  }
}

How fees work

Payout fees are added on top of the amount. The recipient gets amount and your balance is debited total_debit = amount + service_fee + network_fee. The network fee is the provider's own estimate where it publishes one. With a 1% fee on 10,000 USDT, the service fee is 100 and the total debit is 10,100 plus any network fee.

Payout statuses

Status	Meaning	Funds
`requested`	Accepted and funds reserved.	Reserved
`under_review`	Waiting for approval by our team.	Reserved
`approved`	Approved and queued for the provider.	Reserved
`processing`	Submitted to the provider.	Reserved
`completed`	Sent. `tx_hash` is set when the provider returns one.	Debited
`rejected`	Rejected by our team; see `rejection_reason`.	Returned
`failed`	The provider could not send it; see `failure_reason`.	Returned
`cancelled`	Cancelled by you before approval.	Returned

Cancel a payout

POST /payouts/{id}/cancel · scope payouts:write. You can cancel only while the status is requested or under_review. Later states return 409 invalid_state.

Common errors

Status	Code	When
422	`insufficient_balance`	Available balance does not cover `total_debit`. `details` shows available and required amounts.
422	`destination_not_supported`	The provider cannot pay to that destination type.
422	`network_required`	A network is required for this currency and provider.
409	`duplicate_reference`	The reference was already used for another payout.
422	`limit_exceeded`	Over a per-transaction or daily payout limit.
503	`service_unavailable`	New payouts are temporarily paused.