Fiat Payout Transfer

A fiat payout transfer converts stablecoins into fiat and delivers the funds to a supported mobile money provider.
This operation is executed through the unified Transfers API using operationType: fiat_payout.

The flow is straightforward:

1. Fetch a rate using the Rates API
2. Submit a transfer using the quoted rate
3. Fund the transfer by sending crypto
4. Celar processes the fiat payout

Create a Fiat Payout Transfer

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/transfer \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: <random_uuid>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "<customer_id>",
    "amount": <cryptoEquivalent>,
    "signature": "<rate_signature>",
    "operationType": "fiat_payout",
    "dev_fee": <percentage>,
    "source": {
      "currency": "<crypto_token>",
      "chain": "<blockchain_network>"
    },
    "destination": {
      "currency": "<fiat_currency>",
      "description": "<payment_description>",
      "serviceProvider": "<fiat_provider>",
      "paymentMethod": "mobile",
      "phoneNumber": "<phone_number>"
    }
  }'

Response

{
  "payment_id": "transfer_2928607dce205ecd",
  "status": "pending",
  "magic_link_url": "https://pay.sandbox.celar.io/transfer_2928607dce205ecd",
  "chain": "base",
  "intermediary_wallet": "0x3c62c211C3211b7EffFa27B49DC967AbB346Bf72",
  "rate": "127.5",
  "amount": 3.922
}

Notes & Important Behavior

Rate Requirements

• You must obtain a rate before submitting a fiat payout
• Both cryptoEquivalent and signature from the rate response are required
• Rate quotes are valid for 5 minutes
• If the provided amount does not match the quoted cryptoEquivalent, the transfer will fail

Phone Number Resolution

• If phoneNumber is provided, it is used

• If omitted:

  • Developer user type → customer’s stored phone number is used
  • PSP user type → PSP’s stored phone number is used

Developer Fees

• dev_fee is a percentage (e.g., 2.5 for 2.5%)
• Only developer user types can set a developer fee and its optional
• Fees are deducted automatically during settlement

Failure Handling

If the fiat payout cannot be off-ramped:

• PSP user type → funds are credited to the PSP Celar wallet
• Developer user type → funds are credited to the customer's celar wallet

Funding & Status Tracking

After the transfer is created, send the exact crypto amount to the returned intermediary_wallet. Once detected and confirmed on-chain, Celar processes the fiat payout automatically.

Transfers move through the following lifecycle:

Status	Description	Webhook
pending	Transfer created, awaiting funding	—
confirmed	Crypto received and confirmed on-chain	✅
settled	Fiat payout completed	✅

You can track progress by:

• Polling the Payments Status API, or
• Subscribing to Webhooks

Once settled, the recipient receives the fiat payout and the transaction is settled.