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.

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>",
    },
    "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"
}