Payouts

Overview

Payouts allow you to send stablecoins out of your Celar custodial wallet to customers or external blockchain addresses.

They represent outbound transfers, such as:

• vendor or supplier payments
• merchant settlements
• cross-border disbursements
• payroll or operational payouts

Celar supports:

• Single payouts (one recipient)
• Mass payouts (multiple recipients in one request)

Prerequisites

Before creating a payout:

• Create and fund a Celar wallet
  All payouts are executed from a custodial wallet you own.
• Create customers
  Each payout must reference a valid customer_id.
• Ensure sufficient balance
  The wallet must hold enough tokens to cover the payout amount and fees.

Single Payout

Send stablecoins to a single recipient.

Request

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/payouts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: <random_uuid>' \
  --header 'Content-Type: application/json' \
  --data '{
    "celar_walletId": "cw_7666ea0866b5829e",
    "token": "USDC",
    "chain": "baseSepolia",
    "dev_fee": 1.5,
    "payout": {
      "customer_id": "cr_1cfcf15c26c99e73",
      "amount": 5,
      "purpose": "vendor_payment",
      "address": "0xF9D9D8a1AC99F9498878f1126b1D2eC3AdD9DA69"
    }
  }'

Notes

• dev_fee

  • Optional
  • Percentage
  • Developers only (PSPs cannot set developer fees)

• address

  • Optional
  • If provided, funds are sent directly to this address
  • If omitted, funds are sent to the customer’s stored wallet address

Mass Payouts (PSP Only)

Send stablecoins to multiple recipients in a single request.

⚠️ Mass payouts are currently enabled only on PSP accounts.

Request

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/masspayouts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: <random_uuid>' \
  --header 'Content-Type: application/json' \
  --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"
      }
    ]
  }'

Notes

• Each payout item is processed independently
• address is optional per recipient
• If no address is provided, Celar uses the customer’s stored external address

Payout Purposes

Each payout must specify a purpose for compliance and reconciliation.

Supported values:

• vendor_payment
• settlement
• crossborder
• salary_payment

Requests with unsupported purposes will be rejected.

Status & Tracking

Payouts move through the following lifecycle:

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

You can:

• Poll the Payments Status API, or
• Subscribe to Webhooks

Settlement

Once a payout is confirmed, the stablecoins are transferred on-chain. The transaction hash can be used to verify settlement on the blockchain.