API reference View as Markdown

Payouts

Every paid charge has one payout: what came in, what was kept, what you are owed, what actually landed and the transaction that carried it. These endpoints only read: payouts go out on their own, and nothing here can raise, redirect or reverse one.

The payout object

Field Description
id, charge string The id of the charge the payout came from. A charge has one payout, written when it is paid.
object "payout" The kind of object.
status "pending" | "sending" | "sent" | "failed" | "manual" Where it has got to. Pending waits for the next run or attempt, sending is broadcast and confirming, sent has confirmed, failed ran out of attempts and manual waits on an address or a person.
asset string The coin it was paid in and goes out in.
gross_amount string What the customer paid, in the coin.
fee_percent, fee_amount string The rate of the platform's fee and what was kept, in the coin.
fee_fiat_amount, fiat_currency, exchange_rate string|null What the fee was worth in your currency, at the rate the charge was locked at.
net_amount string What you are owed, before the chain's own fee.
network_fee, sent_amount string|null What the chain charged and what therefore reached you, once it has been broadcast.
payout_address string|null Where it goes, as you had it configured when the charge was paid. Null while it waits for an address.
payout_txid, explorer_url string|null The transaction that carried it, and its page on a block explorer.
attempts, last_error integer, string|null How many times forwarding has been tried, and why the last try did not work or why it is held.
next_attempt_at string|null When it may go out next, such as when a newly saved address has finished waiting.
sent_at, confirmed_at, created_at string|null When it was broadcast, when it confirmed and when the books were written, as ISO 8601 timestamps in UTC.

Endpoints

  • GET /v1/payouts List payouts, newest first. Filter with ?status=, ?asset= and ?search= (a charge id or a transaction hash).
  • GET /v1/payouts/summary Add up, per coin, what has been paid out, what is on its way and what is still owed. In the mode of the key, and not paged.
  • GET /v1/payouts/{id} Retrieve the payout of a charge, by the charge's id. Answers 404 until the charge is paid.

Example: read a payout

curl https://api.velirapay.com/v1/payouts/2t4bcuqkpkoy \
  -H "Authorization: Bearer vp_live_…"

{
  "data": {
    "id": "2t4bcuqkpkoy",
    "object": "payout",
    "charge": "2t4bcuqkpkoy",
    "status": "sent",
    "asset": "USDT",
    "gross_amount": "11.014175",
    "fee_percent": "3",
    "fee_amount": "0.330425",
    "net_amount": "10.68375",
    "network_fee": "0.081611",
    "sent_amount": "10.602139",
    "payout_address": "0x7099…79C8",
    "payout_txid": "0x9a4f…c21e",
    "explorer_url": "https://etherscan.io/tx/0x9a4f…c21e",
    "confirmed_at": "2026-11-02T21:00:04.000000Z",
    …
  }
}

The summary

GET /v1/payouts/summary answers with one row per coin the account has been paid in, and meta.mode:

Field Description
asset string The coin this row adds up.
payouts integer How many paid charges it covers.
gross_amount, fee_amount string What came in, and what was kept in fees.
paid_out_amount string What has reached you.
in_flight_amount string What is on its way and waiting to confirm.
owed_amount string What is still owed to you and has not left yet.
network_fee_amount string What the chains charged to forward it.
waiting_for_address integer How many payouts wait for you to give an address for this coin.

Read how a payment becomes a payout, who pays the network and which payouts wait →