Skip to main content

FX Payin

An FX payin collects local fiat into a PSP or customer custody balance. Unlike fiat_payin, it does not quote into stablecoins and does not settle into 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_payin transfer with the customer's fiat collection details
  2. Celar creates the underlying collection request
  3. The customer completes the collection through the supported bank or mobile rail
  4. Funds settle into the PSP or customer custody balance
  5. Track completion through Payment Statuses or Webhooks

Prerequisites​

  • A valid customer_id: see Register a Customer
  • A unique Idempotency-Key for the request
  • The collection currency and rail must match the supported combinations:
    • NGN uses bank
    • KES uses mobile with MPESA
    • UGX uses mobile with MTN or AIRTEL
info

fx_payin does not require a rate signature, a destination crypto wallet, or a Celar walletId.

Submit the transfer​

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_payin",
    "customer_id": "cr_70be275b878077ab",
    "amount": 1000,
    "source": {
      "currency": "KES",
      "description": "KES custody funding",
      "paymentMethod": "mobile",
      "serviceProvider": "MPESA",
      "phoneNumber": "+254719599951",
      "accountName": "Frankline Mosigisi",
      "reference": "fx-payin-kes-ref101"
    }
  }'

Response​

NGN bank collections return virtual account instructions. Mobile collections are also asynchronous and should be tracked by webhook or payment status polling.

{
  "message": "Follow the payment details below to complete your payin",
  "data": {
    "paymentId": "transfer_69cdec693604074f",
    "status": "pending",
    "paymentDetails": {
      "accountName": "Frankline Mosigisi",
      "accountNumber": "1234567890",
      "bankName": "Providus Bank",
      "expiryDate": "2026-06-05T05:00:00.000Z",
      "expiryInSeconds": 7200,
      "amount": 100000,
      "currency": "NGN"
    }
  }
}
NGN virtual account expiry

NGN bank collections use a temporary virtual account. It is valid for 2 hours and must receive the exact quoted amount.

Field reference​

FieldRequiredDescription
operationTypeYesfx_payin
customer_idYesThe customer whose custody balance is being funded
amountYesFiat amount to collect into custody
source.currencyYesNGN, KES, or UGX
source.descriptionYesInternal description for reconciliation
source.paymentMethodYesMust match the source currency: bank for NGN, mobile for KES/UGX
source.serviceProviderConditionalRequired for mobile collections: MPESA, MTN, or AIRTEL depending on currency
source.phoneNumberConditionalRequired for mobile collections in E.164 format
source.accountNameConditionalRequired when source.phoneNumber is provided for a mobile collection
source.referenceNoYour own reference ID
source.purpose_of_transactionNoOptional declared reason for the collection

Purpose of transaction​

Supported values
ValueDescription
GOODS_PURCHASEPayment for physical goods or merchandise.
SERVICES_PAYMENTPayment for services rendered.
INVOICE_PAYMENTSettlement of an issued invoice.
LOAN_REPAYMENTRepayment of a loan or credit obligation.
BILLS_PAYMENTPayment of utilities, subscriptions, or recurring bills.
SALARY_AND_WAGESSalary, payroll, or wage disbursement.
P2P_TRANSFERPerson-to-person transfer between individuals.
REMITTANCEDomestic or cross-border transfer to a beneficiary.
DONATIONCharitable or personal donation.
GRANTS_AND_SCHOLARSHIPSFunding for grants, bursaries, or scholarships.
TRAVEL_AND_ACCOMMODATIONPayment for travel, lodging, or related expenses.
TAX_PAYMENTTax remittance to a government or regulatory authority.
INSURANCE_PREMIUMPayment of an insurance premium.
FAMILY_SUPPORTFinancial support sent to family members.
EDUCATIONTuition fees, school expenses, or educational costs.
GIFT_AND_DONATIONPersonal gift or charitable contribution.
MEDICAL_TREATMENTPayment for medical or healthcare services.
MAINTENANCE_EXPENSESOngoing maintenance or upkeep costs.
TRAVELTravel-related expenses.
SMALL_VALUE_REMITTANCELow-value cross-border remittance.
LIBERALIZED_REMITTANCERemittance under a liberalized scheme.
CONSTRUCTION_EXPENSESCosts related to construction or building projects.
HOTEL_ACCOMMODATIONPayment for hotel or lodging services.
ADVERTISING_EXPENSESMarketing or advertising costs.
ADVISORY_FEESFees for consulting or advisory services.
BUSINESS_INSURANCEBusiness-related insurance payment.
INSURANCE_CLAIMSPayment of an insurance claim.
DELIVERY_FEESShipping or delivery charges.
EXPORTED_GOODSPayment for goods exported internationally.
SERVICE_CHARGESGeneral service or processing charges.
LOAN_PAYMENTLoan instalment or repayment.
OFFICE_EXPENSESOffice supplies or operational costs.
PROPERTY_PURCHASEPayment for real estate or property acquisition.
PROPERTY_RENTALRent payment for residential or commercial property.
ROYALTY_FEESRoyalties for intellectual property or licensing.
SHARES_INVESTMENTInvestment in shares or equities.
FUND_INVESTMENTInvestment into a fund or financial instrument.
TRANSPORTATION_FEESTransport or logistics costs.
UTILITY_BILLSPayment for electricity, water, gas, or internet.
PERSONAL_TRANSFERGeneral personal transfer with no specific category.
SALARY_PAYMENTSalary disbursement to an employee.
OTHER_FEESMiscellaneous fees not covered by other categories.
COMPUTER_SERVICESPayment for IT or software services.
REWARD_PAYMENTReward, bonus, or incentive payment.
INFLUENCER_PAYMENTPayment to a content creator or influencer.