Fiat Payout

A fiat payout converts stablecoins into fiat currency and delivers funds to a customer's mobile money wallet, bank account, or via SWIFT. It requires a rate quote before submission.

There are two flows depending on whether you provide a source.walletId:

Flow	How it's funded
Without walletId	Celar creates an intermediary wallet: you send crypto to it to fund the payout
With walletId	Celar debits your specified Celar wallet directly: no on-chain funding step needed

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

Rate validity

Rate quotes are valid for 5 minutes. Submit the transfer before the signature expires. If the amount doesn't match the quoted cryptoEquivalent, the transfer will fail.

---

Flow 1: Without walletId (external funding)

Use this flow when you don't have a pre-funded Celar wallet. Celar provides an intermediary wallet address you fund on-chain to trigger the payout.

How it works

1. Fetch a rate from the Rates API: get cryptoEquivalent and signature
2. Submit the fiat_payout transfer without a walletId
3. Celar returns an intermediary_wallet address
4. Send the exact crypto amount to that address on-chain
5. Celar detects the deposit and processes the fiat delivery
6. A webhook fires when status moves to settled

Step 1: Get a rate

Before submitting, fetch a rate quote from the Rates API. This returns the cryptoEquivalent and signature you need for the next step.

Step 2: Submit the transfer

Mobile Money

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base"
    },
    "destination": {
      "currency": "KES",
      "description": "Mobile money payout to customer",
      "reference": "PAYOUT-23923",
      "serviceProvider": "MPESA",
      "paymentMethod": "mobile",
      "phoneNumber": "+254712345678",
      "purpose_of_transaction": "REMITTANCE"
    }
  }'

Bank

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base"
    },
    "destination": {
      "currency": "KES",
      "description": "Bank payout to customer",
      "reference": "PAYOUT-23923",
      "paymentMethod": "bank",
      "bankCode": "<bank_code_from_banks_endpoint>",
      "accountNumber": "0123456789",
      "purpose_of_transaction": "REMITTANCE"
    }
  }'

SWIFT

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base"
    },
    "destination": {
      "currency": "USD",
      "description": "SWIFT payout to customer",
      "reference": "PAYOUT-23923",
      "paymentMethod": "swift",
      "swiftCode": "EQBLKENA",
      "accountNumber": "0123456789",
      "purpose_of_transaction": "SMALL_VALUE_REMITTANCE"
    }
  }'

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
}

Step 3: Fund the transfer

Send exactly amount of the source token to the intermediary_wallet address. Celar detects the on-chain deposit and automatically processes the fiat delivery.

---

Flow 2: With walletId (internal wallet funding)

Use this flow when you have a pre-funded Celar wallet. Celar debits it directly: no intermediary wallet or on-chain funding step required.

How it works

1. Fetch a rate from the Rates API: get cryptoEquivalent and signature
2. Submit the fiat_payout transfer with source.walletId set to your Celar wallet
3. Celar debits the wallet and immediately processes the fiat delivery
4. A webhook fires when status moves to settled

Step 1: Get a rate

Before submitting, fetch a rate quote from the Rates API. This returns the cryptoEquivalent and signature you need for the next step.

Step 2: Submit the transfer

Mobile Money

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5"
    },
    "destination": {
      "currency": "KES",
      "description": "Mobile money payout to customer",
      "reference": "PAYOUT-23923",
      "serviceProvider": "MPESA",
      "paymentMethod": "mobile",
      "phoneNumber": "+254712345678",
      "purpose_of_transaction": "REMITTANCE"
    }
  }'

Bank

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5"
    },
    "destination": {
      "currency": "KES",
      "description": "Bank payout to customer",
      "reference": "PAYOUT-23923",
      "paymentMethod": "bank",
      "bankCode": "<bank_code_from_banks_endpoint>",
      "accountNumber": "0123456789",
      "purpose_of_transaction": "REMITTANCE"
    }
  }'

SWIFT

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "signature": "sig_8c23dc5c3140a72b",
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5"
    },
    "destination": {
      "currency": "USD",
      "description": "SWIFT payout to customer",
      "reference": "PAYOUT-23923",
      "paymentMethod": "swift",
      "swiftCode": "EQBLKENA",
      "accountNumber": "0123456789",
      "purpose_of_transaction": "SMALL_VALUE_REMITTANCE"
    }
  }'

Response

{
  "message": "Payout Success"
}

No intermediary_wallet is returned: the payout is triggered immediately from your Celar wallet balance.

US customers

USA customers require destination.transfer_type in the request. The signature field is not required for US customer payouts.

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": "fiat_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 3.922,
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5"
    },
    "destination": {
      "currency": "USD",
      "description": "ACH payout to US customer",
      "reference": "PAYOUT-23923",
      "paymentMethod": "bank",
      "transfer_type": "ach_credit",
      "accountNumber": "0123456789",
      "purpose_of_transaction": "REMITTANCE"
    }
  }'

Field reference

Field	Required	Description
operationType	Yes	fiat_payout
customer_id	Yes	The customer receiving the payout
amount	Yes	Crypto amount: use cryptoEquivalent from the rate response
signature	Yes (non-US)	Rate signature from the Rates API
source.currency	Yes	USDC or USDT
source.chain	Yes	base, polygon, arbitrum, or baseSepolia
source.walletId	No	If set, debits this Celar wallet directly (Flow 2)
destination.currency	Yes	Fiat currency: e.g. KES, NGN, GHS, USD
destination.paymentMethod	Yes	mobile, bank, or swift
destination.serviceProvider	Conditional	Required for mobile: e.g. MPESA, MTN, AIRTEL
destination.bankCode	Conditional	Required for bank: bank code from the banks endpoint
destination.swiftCode	Conditional	Required for swift: recipient bank's BIC/SWIFT code
destination.transfer_type	Conditional	Required for US customers: ach_credit, same_day_ach_credit, or rtp_credit
destination.phoneNumber	Conditional	Required for mobile (E.164 format)
destination.accountNumber	Conditional	Required for bank and swift: customer's account number or IBAN
destination.description	Yes	Internal description
destination.reference	No	Your own reference ID
destination.purpose_of_transaction	No	See supported values below

Purpose of transaction

Supported values

Value	Description
GOODS_PURCHASE	Payment for physical goods or merchandise.
SERVICES_PAYMENT	Payment for services rendered.
INVOICE_PAYMENT	Settlement of an issued invoice.
LOAN_REPAYMENT	Repayment of a loan or credit obligation.
BILLS_PAYMENT	Payment of utilities, subscriptions, or recurring bills.
SALARY_AND_WAGES	Salary, payroll, or wage disbursement.
P2P_TRANSFER	Person-to-person transfer between individuals.
REMITTANCE	Domestic or cross-border transfer to a beneficiary.
DONATION	Charitable or personal donation.
GRANTS_AND_SCHOLARSHIPS	Funding for grants, bursaries, or scholarships.
TRAVEL_AND_ACCOMMODATION	Payment for travel, lodging, or related expenses.
TAX_PAYMENT	Tax remittance to a government or regulatory authority.
INSURANCE_PREMIUM	Payment of an insurance premium.
FAMILY_SUPPORT	Financial support sent to family members.
EDUCATION	Tuition fees, school expenses, or educational costs.
GIFT_AND_DONATION	Personal gift or charitable contribution.
MEDICAL_TREATMENT	Payment for medical or healthcare services.
MAINTENANCE_EXPENSES	Ongoing maintenance or upkeep costs.
TRAVEL	Travel-related expenses.
SMALL_VALUE_REMITTANCE	Low-value cross-border remittance.
LIBERALIZED_REMITTANCE	Remittance under a liberalized scheme.
CONSTRUCTION_EXPENSES	Costs related to construction or building projects.
HOTEL_ACCOMMODATION	Payment for hotel or lodging services.
ADVERTISING_EXPENSES	Marketing or advertising costs.
ADVISORY_FEES	Fees for consulting or advisory services.
BUSINESS_INSURANCE	Business-related insurance payment.
INSURANCE_CLAIMS	Payment of an insurance claim.
DELIVERY_FEES	Shipping or delivery charges.
EXPORTED_GOODS	Payment for goods exported internationally.
SERVICE_CHARGES	General service or processing charges.
LOAN_PAYMENT	Loan instalment or repayment.
OFFICE_EXPENSES	Office supplies or operational costs.
PROPERTY_PURCHASE	Payment for real estate or property acquisition.
PROPERTY_RENTAL	Rent payment for residential or commercial property.
ROYALTY_FEES	Royalties for intellectual property or licensing.
SHARES_INVESTMENT	Investment in shares or equities.
FUND_INVESTMENT	Investment into a fund or financial instrument.
TRANSPORTATION_FEES	Transport or logistics costs.
UTILITY_BILLS	Payment for electricity, water, gas, or internet.
PERSONAL_TRANSFER	General personal transfer with no specific category.
SALARY_PAYMENT	Salary disbursement to an employee.
OTHER_FEES	Miscellaneous fees not covered by other categories.
COMPUTER_SERVICES	Payment for IT or software services.
REWARD_PAYMENT	Reward, bonus, or incentive payment.
INFLUENCER_PAYMENT	Payment to a content creator or influencer.