Transfers

Overview

The /transfer endpoint is a unified interface for handling multiple types of fund operations within the Celar platform. This single endpoint streamlines payments, withdrawals, and transfers by supporting various operation types with consistent request/response formats.

Examples below use the sandbox environment. For production, switch the API base URL to https://api.celar.io/api/v1 and hosted payment links to https://pay.celar.io.

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) to specify the method of fund delivery and authorization. They authorize currency conversion requests and ensure rate integrity.

🇺🇸 United States Only

These transfer types are available exclusively for US-based customers.

Available Methods:

wire – Fast bank transfers for large amounts(fiat_payins)
ach_debit – Pull funds from bank accounts (standard)(fiat_payins)
ach_credit – Push funds to bank accounts (payouts)(fiat_payouts)
same_day_ach_credit – Express ACH for same-day delivery(fiat_payouts)
rtp_credit – Real-time instant payments(fiat_payouts)

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

Operation Examples

1. Fiat Payout (`fiat_payout`)

Convert cryptocurrency to fiat and send to mobile money/bank accounts.

Request Example:

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
}

Or if from an Internal wallet (Celar wallet)

{
  "message":"Payout Success"
}

2. Fiat Payin (`fiat_payin`)

Accept fiat payments and convert to stablecoins.

Request Example:

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": <fiatAmount>,
    "signature": "<rate_signature>",
    "operationType": "fiat_payin",
    "dev_fee": <percentage>,
    "destination": {
      "currency": "<crypto_token>",
      "chain": "<blockchain_network>"
    },
    "source": {
      "currency": "<fiat_currency>",
      "description": "<payment_description>",
      "serviceProvider": "<fiat_provider>",
      "paymentMethod": "mobile",
      "reference":"<reference>",
      "phoneNumber": "<phone_number>"
    }
  }'

Response

{
 "success":true,
 "message":"Payin is pending. Please check webhook"
}

3. Payout/Withdraw (`payout`)

Send cryptocurrency from a Celar wallet to any external wallet address. Request Example:

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": <cryptoAmount>,
    "operationType": "payout",
    "dev_fee": <percentage>,
    "source": {
      "currency": "<crypto_token>",
      "chain": "<blockchain_network>",
      "reference":"<reference>",
      "description": "<payment_description>",
      "walletId": "<wallet_id>"
    },
    "destination": {
      "address": "<valid wallet address>",
      "description":<description>
    }
  }'

Response

{
 "status":"settled",
 "message":"payout sent successfully",
 "tx_hash":"transaction hash..."
}

4. Refunds (`refunds`)

Return funds to the original payment source, triggered by PSP refund requests.

Request Example:

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": <cryptoAmount>,
    "operationType": "refund",
    "source": {
      "paymentId": "<payment id>",
      "walletId": "<wallet id>",
      "type":"partial|full",
      "chain": "<blockchain_network>",
    }
    
  }'

Response

{
 "id":"transfer_39fdf5b02cda5670",
 "amount":1,
 "message":"Refund completed successfully",
 "tx_hash":"transaction hash..."
}

5. Payin (`payin`)

Accept cryptocurrency deposits. Request Example:

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": <cryptoAmount>,
    "operationType": "payin",
    "source": {
      "currency": "<cryptoToken",
      "chain": "<blockchain_network>",
      "description":"<description>,
      "reference":"reference"
    }
    "destination":{
    "address": "<valid wallet address>"
    }
    
  }'

Response

{
 "payment_id":"transfer_39fdf5b02cda5670",
 "status":"pending",
 "magic_link_url":"https://pay.sandbox.celar.io/transfer_272638d79c97cdb3
",
 "chain":"baseSepolia",
 "intermediary_wallet":"0x60071d1b7ADF590db7b04D32814e160e99848195",
 "token_address":"0xc7a0895345C2BD66EF974A0B60372e2EcD80b1"
}

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

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.

Overview​

Supported Operation Types​

Prerequisites​

API Authentication​

Understanding Signatures​

Understanding Transfer Types​

Transfer Components​

Operation Examples​

1. Fiat Payout (fiat_payout)​

Response​

2. Fiat Payin (fiat_payin)​

Response​

3. Payout/Withdraw (payout)​

Response​

4. Refunds (refunds)​

Response​

5. Payin (payin)​

Response​

Purpose of Transaction​

Overview

Supported Operation Types

Prerequisites

API Authentication

Understanding Signatures

Understanding Transfer Types

Transfer Components

Operation Examples

1. Fiat Payout (`fiat_payout`)

Response

2. Fiat Payin (`fiat_payin`)

Response

3. Payout/Withdraw (`payout`)

Response

4. Refunds (`refunds`)

Response

5. Payin (`payin`)

Response

Purpose of Transaction