FX Payout

An FX payout sends fiat from a PSP or customer custody balance to a beneficiary's bank account or mobile wallet. Unlike fiat_payout, it does not start from on-chain stablecoins and does not use a Celar wallet.

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

How it works

1. Submit an fx_payout transfer with the source custody currency and destination payout details
2. Celar debits the underlying custody balance
3. Celar creates or reuses the beneficiary and submits the fiat payout
4. Track completion through Payment Statuses or Webhooks

Prerequisites

• A valid customer_id: see Register a Customer
• Sufficient custody balance in source.currency
• A unique Idempotency-Key for the request

info

fx_payout does not require a rate signature, a source crypto wallet, or a Celar walletId.

warning

SWIFT appears in the schema enum, but the transfer schema description says SWIFT FX payouts are not supported yet.

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": "fx_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 10000,
    "source": {
      "currency": "NGN"
    },
    "destination": {
      "description": "Payout to Kenya from NGN wallet",
      "paymentMethod": "mobile",
      "currency": "KES",
      "serviceProvider": "MPESA",
      "phoneNumber": "+254700000000",
      "reference": "fx-ngn-kes-test-001",
      "purpose_of_transaction": "SERVICES_PAYMENT"
    }
  }'

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": "fx_payout",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 10000,
    "source": {
      "currency": "NGN"
    },
    "destination": {
      "description": "Bank payout from NGN custody",
      "paymentMethod": "bank",
      "currency": "KES",
      "accountNumber": "0123456789",
      "bankCode": "044",
      "reference": "fx-ngn-bank-test-001",
      "purpose_of_transaction": "SERVICES_PAYMENT"
    }
  }'

Response

{
  "payment_id": "transfer_9b858103f825a5b4",
  "status": "pending"
}

The payout is asynchronous. Poll Payment Statuses or subscribe to Webhooks to detect completion.

Field reference

Field	Required	Description
operationType	Yes	fx_payout
customer_id	Yes	The customer receiving the payout
amount	Yes	Source spend amount in the custody currency
source.currency	Yes	Custody wallet currency to debit, for example NGN
destination.currency	Yes	Fiat currency the beneficiary receives, for example KES or XOF
destination.paymentMethod	Yes	mobile or bank. swift is defined in schema but not currently supported for FX payouts
destination.description	Yes	Internal description for reconciliation
destination.reference	No	Your own reference ID
destination.country	Conditional	Required for ambiguous multi-country currencies such as XOF
destination.serviceProvider	Conditional	Required for mobile payouts
destination.phoneNumber	Conditional	Required for mobile payouts in E.164 format
destination.accountNumber	Conditional	Required for bank payouts
destination.bankCode	Conditional	Required for bank payouts
destination.purpose_of_transaction	No	Declared reason for the payout

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.