Payins

Pay-ins are how you accept stablecoin deposits from customers into Celar. They represent inbound payments and are the starting point for most integrations.

Prerequisites

Before creating a pay-in you must:

Create a Wallet
Every organization needs at least one custodial wallet in Celar. This wallet is where funds will be routed once the pay-in is confirmed. See Wallets.

Create a Customer
Each pay-in must be linked to a customer_id. Create a customer first via API or add them via the dashboard. See Customers.

Get Test Tokens
To simulate payins on our sandbox environment, you’ll need test tokens (USDT, USDC). Use the Celar Faucet to request tokens on supported chains (base and arbitrum). These tokens hold no real world value.

1. Create a Pay-in

Once you have your wallet set up and a customer_id, you can create a new pay-in.

Request

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/payments/payins \
  --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": "10.00",
    "currency": "USDC",
    "chain": "base",
    "reference": "INV-2025-009",
    "description": "Payment for Order #009",
    "metadata": {
      "order_id": "009",
      "buyer_email": "johndoe@example.com"
    }
  }'

Response

{
  "payment_id": "pay_100521dccb3f9ad0",
  "status": "pending",
  "magic_link_url": "https://pay.celar.io/pay_100521dccb3f9ad0",
  "chain": "base",
  "intermediary_wallet": "0xf60b63b2cAea411FA8e69b2806eA763f0629654E",
  "token_address": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
}

Key fields:

• magic_link_url → hosted checkout link for the customer that contains information needed to complete a payment.
• intermediary_wallet → temporary wallet generated for this pay-in. Funds are first received here before being sent to the Celar wallet.
• status → starts as pending until funds are detected.

Chains

When creating a request, you must specify a chain. Celar currently supports several blockhains.

-> "best" - Celar automatically routes to the optimal chain.

-> Or specify a chain directly (e.g. "arbitrum").

See Supported Chains for the full list and details.

2. Track Status

After creating a pay-in, you need to track its lifecycle:

• Poll the Payments Status API to check the latest status or subscribe to Webhooks to receive events in real time.
• A pay-in expires after 20 minutes. If it lapses, create a new one.

Pay-in Lifecycle

Status	Meaning	Webhook Triggered
pending	Pay-in created, waiting for customer transfer.	—
confirmed	Funds detected in intermediary wallet and KYT checks passed.	✅
settling	Funds moving from intermediary wallet → celar wallet.	—
settled	Funds available in celar wallet.	✅
failed	Pay-in expired or failed KYT (blocked by compliance).	✅
payment_mismatch	Funds received, but amount does not match expected.	✅
settlement_failed	Funds detected but settlement from intermediary → celar failed.	✅

⚠️ Notes:

• Webhooks fire at confirmed, settled, failed, payment_mismatch, and settlement_failed.

3. Settlement

Once a pay-in reaches settled, the stablecoins are available in your celar wallet. From there, you can:

• Make payouts to customers.
• Execute withdrawals to your treasury.
• Or hold funds for later reconciliation.

4. Magic Links & QR Codes

Celar provides Magic Links and QR Codes as two ways to present the payment details to your customer. Both resolve to the same pay-in object and expose details such as amount, currency, chain, and intermediary wallet.

⚠️ Note: Magic Links and QR Codes only expose payments with status pending or confirmed. Payments in failed, settling, or settled states are not accessible.

Magic Links

Magic Links are customer-facing URLs. When opened, they display the payment details so the customer use them to can transfer funds.

Example Request

curl --request GET \
  --url https://pay.sandbox.celar.io/<payin_id> \
  --header 'Accept: application/json'

Example Response

{
  "payment_id": "payin_47cb728afdb91063",
  "amount": "10.000",
  "currency": "USDC",
  "chain": "base",
  "status": "pending",
  "intermediary_wallet": "0xCa2e4E68A1f8cce76df0B6E16aDdda780f66F0A7",
  "created_at": "2025-09-25T11:34:16.144Z"
}

QR Codes

Each payment also provides a QR code endpoint, which encodes the same details as the Magic Link. Customers can scan the QR code using a wallet (MetaMask, Rabby, TrustWallet).

When scanned, the wallet will:

1. Open the payment request.
2. Display the destination (intermediary wallet), amount, and chain.
3. Prompt the customer to confirm and sign the transaction.

Example QR URL

https://pay.sandbox.celar.io/<payin_id>/scan