Transfers
Overview
This page covers the key requirements and transfer-specific details you need before sending transfer requests with Celar.
Supported Operation Types
| Operation Type | Description | Signature Required (Non USA customers) |
|---|---|---|
fiat_payout | Convert cryptocurrency to fiat currency and send to external bank/mobile money accounts | Required |
payin | Accept cryptocurrency deposits into a PSP or customer wallet | Not Required |
payout | Send cryptocurrency from a Celar wallet to any external wallet address | Not Required |
refund | Return funds to the original payment source, triggered by PSP refund requests | Not Required |
fiat_payin | Accept fiat payments and convert to stablecoins in a Celar wallet | Required |
Prerequisites
API Authentication
- Valid API key with appropriate permissions
- Bearer token authentication for all requests
- Idempotency key for preventing duplicate operations
Understanding Signatures
Signatures are cryptographic tokens required for fiat-related operations (fiat_payout and fiat_payin). They authorize currency conversion requests and ensure rate integrity.
Important: Signatures are optional for US customers. Always generate signatures using the Rates API immediately before making transfer requests to ensure accurate exchange rates.
Understanding Transfer Types
Transfer types are used for fiat_payout and fiat_payin operations to specify the method of fund delivery. They apply only to US-based customers - non-US customers use standard bank or mobile money routing and do not set a transfer_type.
transfer_type is required on fiat payin and fiat payout requests for US customers. Omitting it for a US customer will fail validation.
Fiat payin - set on source.transfer_type:
| Value | Description |
|---|---|
wire | Bank wire transfer - fast, for large amounts |
ach_debit | ACH pull from the customer's linked bank account (1-3 business days) |
Fiat payout - set on destination.transfer_type:
| Value | Description |
|---|---|
ach_credit | Standard ACH push to the customer's bank (1-3 business days) |
same_day_ach_credit | Same-day ACH - expedited delivery within the business day |
rtp_credit | Real-time payment - instant delivery |
ach_debit requires the customer's bank to be linked via Plaid. See Plaid Bank Linkage below.
Transfer Components
Every transfer consists of two main parts:
| Component | Description |
|---|---|
| Source | Defines where funds originate (crypto wallet or fiat account) |
| Destination | Defines where funds are delivered |
Purpose of Transaction
purpose_of_transaction specifies the business or personal reason for a fiat payout. It helps classify the transfer for compliance, reporting, and payout processing.
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. |
Plaid Bank Linkage (US Only)
Plaid linkage is optional for US customers. It is required only when using ach_debit (pulling funds from the customer's bank account for a fiat payin). For wire transfers, ach_credit, same_day_ach_credit, and rtp_credit payouts, Plaid linkage is not needed - the bank details added via PATCH /customers/payment-details are used directly.
Step 1: Get a Plaid Link token
Request a short-lived token to initialise the Plaid Link UI in your frontend.
curl --request GET \
--url 'https://api.sandbox.celar.io/api/v1/customers/plaid-token?customer_id=cr_53c79dae85d2cee2' \
--header 'Authorization: Bearer <your_api_key>'
Pass the returned link_token to the Plaid Link SDK. The customer authenticates and selects their bank account inside Plaid Link. On success, Plaid returns a public_token to your callback.
Step 2: Register the institution
Exchange the public_token for a permanent bank linkage. Declare which transfer types the customer is permitted to use via transfer_types.
curl --request POST \
--url https://api.sandbox.celar.io/api/v1/customers/institution \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
"customer_id": "cr_53c79dae85d2cee2",
"public_token": "<plaid_public_token>",
"customer_webhook_url": "https://your-app.com/webhooks/plaid",
"transfer_types": ["ach_debit", "ach_credit", "rtp_credit"]
}'
| Field | Required | Description |
|---|---|---|
customer_id | Yes | The customer whose bank account is being linked |
public_token | Yes | Short-lived token returned by Plaid Link on success |
customer_webhook_url | Yes | HTTPS URL Plaid will call with transfer status updates |
transfer_types | Yes | Array of permitted transfer types - at least one of ach_debit, ach_credit, rtp_credit |
Response
{
"message": "Financial institution registered successfully",
"address_id": "addr_a1b2c3d4e5f6"
}
The address_id identifies the Plaid-linked bank address and is stored on the customer record by Celar for routing ACH and RTP transfers.