Payin

A payin accepts a stablecoin deposit from a customer. Celar generates a hosted payment link and an intermediary wallet address: the customer sends funds there, and Celar handles the rest.

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

How it works

1. Submit a payin request with the customer ID, amount, and source chain/token
2. Celar returns a magic_link_url and an intermediary_wallet address
3. Share the magic link with the customer: or use the wallet address directly
4. The customer sends the exact amount on-chain
5. Celar detects the deposit and settles funds to your wallet
6. A webhook fires when status moves to settled

Prerequisites

• A valid customer_id: see Register a Customer
• A unique Idempotency-Key for the request (UUID recommended)

Request

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": "payin",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 50,
    "source": {
      "currency": "USDC",
      "chain": "base",
      "description": "Customer deposit",
      "reference": "INV-23923"
    },
    "destination": {
      "address": "0xabc123..."
    }
  }'

info

destination.address is optional. If omitted, funds settle to your Celar wallet. If provided, Celar forwards the funds to that address after receipt.

Response

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

Field	Required	Description
payment_id		Unique ID: use it to poll status or retrieve webhooks
magic_link_url		Hosted payment page to share with the customer
intermediary_wallet		On-chain address the customer sends funds to
token_address		Contract address of the token on the specified chain

Field reference

Field	Required	Description
operationType	Yes	payin
customer_id	Yes	The customer making the deposit
amount	Yes	Amount in the source token
source.currency	Yes	USDC or USDT
source.chain	Yes	base, polygon, arbitrum, or baseSepolia
source.description	Yes	Internal label for reconciliation
source.reference	No	Your own reference (e.g. invoice number)
destination.address	No	Forward funds to this address after receipt

See Payment Statuses and Webhooks for more.