Payouts

Payouts let you send stablecoins from your Celar custodial wallet to your customers.
They represent outbound money movement — for example, paying vendors, merchants, or end-users.

Prerequisites

Before creating a payout you must:

Create and Fund a Wallet
Every payout is executed from one of your custodial wallets.
Use the Wallets API to provision a wallet, and ensure it is pre-funded.
Keep the celar_walletId handy.

Create a Customer
Each payout must be linked to a customer_id. See Customers.

Get Test Tokens
To simulate payouts on our sandbox environment, you’ll need test tokens (USDT, USDC). Use the Celar Faucet to request tokens on supported chains (base and arbitrum). These tokens hold no real world value.

1. Create a Payout

Once you have a funded wallet and a customer_id, you can create one or more payouts in a batch.

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": "<celar_walletId>",
    "token": "USDC",
    "payouts": [
      {
        "customer_id": "<customer_id>",
        "amount": 1,
        "purpose": "vendor_payment"
      }
    ]
  }'

Response

{
  "message": "1 payouts sent successfully",
  "batch_id": "batch_1d1567b557cf",
  "tx_hash": "0x75cf7be970b69e8b30c4489ec23b20ffa44e98b3b88f0d37872e4b9db1bd97cd",
  "status": "payout_sent"
}

Key fields:

• batch_id → identifier for the payout batch.
• tx_hash → blockchain transaction hash for the payout.
• status → reflects the lifecycle of the payout.

Purposes

Each payout must include a purpose. This helps with compliance, reporting, and reconciliation.

Allowed values:

• vendor_payment → paying a supplier or vendor.
• settlement → merchant settlement / clearing funds.
• crossborder → international remittance.
• salary_payment → payroll / employee disbursement.

Any request with an unsupported purpose will be rejected.

2. Track Status

A payout moves through the following lifecycle:

Status	Meaning	Webhook Triggered
pending	Payout created, queued for execution.	—
payout_sent	Payout transaction confirmed on-chain.	✅
failed	Payout could not be completed (e.g., insufficient funds).	✅

You can:

• Poll the Payments API to check the latest status.
• Or subscribe to Webhooks for real-time updates.

3. Settlement

Once a payout reaches payout_sent, the stablecoins are successfully transferred to your customer’s address. You can view the transaction on-chain using the tx_hash.

Chains

When creating a request, you must specify a chain. Celar currently supports several blockhains.

-> "best" - Celar automatically routes to the optimal chain.

-> Or specify a chain directly (e.g. "arbitrum").

See Supported Chains for the full list and details.