Mass Payouts

Overview

Mass Payouts allow you to send stablecoins out of your Celar custodial wallet to customers or external blockchain addresses, to multiple recipients in one request. They represent outbound transfers, such as:

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

Prerequisites

Before creating a mass payout:

• Create and fund a Celar wallet
  All mass 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.

⚠️ 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

Payouts 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.