Payout

A payout sends stablecoins from a Celar wallet to a customer's external wallet address. It settles on-chain immediately and returns a transaction hash when complete.

Examples use the sandbox environment. For production, replace api.sandbox.celar.io with api.celar.io.

How it works

1. Submit a payout request with the customer ID, amount, source wallet, and destination address
2. Celar debits your specified Celar wallet
3. Funds are sent on-chain to the destination address
4. Response returns settled status and a tx_hash

Prerequisites

• A valid customer_id: see Register a Customer
• A funded Celar wallet (walletId): see Create a Wallet
• A unique Idempotency-Key for the request

Request

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/transfer \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique_uuid>' \
  --data '{
    "operationType": "payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 25,
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5",
      "description": "User withdrawal",
      "reference": "PAYOUT-001"
    },
    "destination": {
      "address": "0xdef456abc789...",
      "description": "Customer withdrawal to external wallet"
    }
  }'

info

destination.address is optional. If omitted, Celar sends funds to the customer's stored wallet address on their profile.

Response

{
  "status": "settled",
  "message": "payout sent successfully",
  "tx_hash": "0x21aa1cbfb389b886e496383f66907fc676b775eb44bb7813abf20ad4e913002a"
}

Field	Required	Description
status		settled on success
tx_hash		On-chain transaction hash: use to verify on a block explorer

Field reference

Field	Required	Description
operationType	Yes	payout
customer_id	Yes	The customer receiving the payout
amount	Yes	Amount in the source token
source.currency	Yes	USDC or USDT
source.chain	Yes	base, polygon, arbitrum, or baseSepolia
source.walletId	Yes	Celar wallet ID to debit funds from
source.description	Yes	Internal label for reconciliation
source.reference	No	Your own reference ID
destination.address	No	External wallet address to send funds to
destination.description	No	Description for the destination entry

See Payment Statuses and Webhooks for more.

Mass Payouts

Send stablecoins to multiple recipients in a single request. Each payout item is processed independently from one Celar wallet.

info

Mass payouts are currently enabled on PSP accounts only.

Prerequisites

• A funded Celar wallet (celar_walletId): see Create a Wallet
• Valid customer_id for each recipient: see Register a Customer
• Sufficient wallet balance to cover all payout amounts and fees
• A unique Idempotency-Key for the request

Request

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/masspayouts \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique_uuid>' \
  --data '{
    "celar_walletId": "cw_458683dd15d5806c",
    "token": "USDT",
    "chain": "baseSepolia",
    "payouts": [
      {
        "customer_id": "cr_2ae76bc76f03437d",
        "amount": 5,
        "purpose": "vendor_payment",
        "address": "0xF9D9D8a1AC99F9498878f1126b1D2eC3AdD9DA69"
      },
      {
        "customer_id": "cr_1cf1b33b939e5e2f",
        "amount": 5,
        "purpose": "vendor_payment",
        "address": "0xF9D9D8a1AC99F9498878f1126b1D2eC3AdD9DA69"
      }
    ]
  }'

Status lifecycle

Status	Description
pending	Payout created, awaiting execution
confirmed	Transaction confirmed on-chain
failed	Execution failed (e.g. insufficient balance)

Poll the Payment Status API or subscribe to Webhooks for updates.

Settlement

Once a payout reaches confirmed, the stablecoins are transferred on-chain. Use the tx_hash returned on individual payouts to verify settlement on a block explorer.

Field reference

Field	Required	Description
celar_walletId	Yes	Celar wallet ID to debit all payouts from
token	Yes	USDC or USDT
chain	Yes	base, polygon, arbitrum, or baseSepolia
payouts[].customer_id	Yes	The customer receiving this payout
payouts[].amount	Yes	Amount to send to this recipient
payouts[].purpose	Yes	vendor_payment, settlement, crossborder, or salary_payment
payouts[].address	No	Recipient's external wallet address. Falls back to the customer's stored address if omitted