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.

Overview

A pay-in allows you to accept stablecoins from a customer.
Funds are first received in a temporary Celar wallet and then routed to the appropriate destination based on your integration type.

• Developers → funds settle into the customer’s Celar wallet
• PSPs → funds settle into the PSP’s Celar wallet

Pay-ins support magic links and QR codes for customer-facing flows.

Prerequisites

Before creating a pay-in:

• Create a Customer

  • Every pay-in must be linked to a customer_id.

• Create a Wallet

  • Developers should create:
    • a customer wallet (to receive the pay-in)
    • a developer wallet (to receive any dev_fee, if used)
  • PSPs should create a PSP wallet to receive the pay-in

Create a 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": "cr_1cfcf15c26c99e73",
    "chain": "best",
    "amount": "9",
    "currency": "USDT",
    "dev_fee": 2.5,
    "reference": "INV-2025-009",
    "description": "Payment for Order #009",
    "address": "<optional_destination_address>",
    "metadata": {
      "order_id": "009",
      "buyer_email": "jane@example.com"
    }
  }'

Parameters

• chain

  • Use "best" to let Celar automatically select the optimal chain

• dev_fee (optional)

  • Percentage fee for developers only

• address (optional)

  • If provided, the incoming pay-in is routed directly to this address
  • If omitted, Celar routes funds to the appropriate custodial wallet

Response

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

• magic_link_url → hosted checkout page for the customer
• intermediary_wallet → temporary wallet where funds must be sent
• status → starts as pending until funds are detected

Important Notes

• Pay-ins expire after 20 minutes if no funds are received

• If dev_fee is set:

  • The developer must have a Celar wallet to receive the fee
  • PSPs cannot set developer fees

• If an explicit address is provided, the pay-in bypasses custodial routing

Developer Fees

• dev_fee is a percentage (e.g., 2.5 for 2.5%)
• Only developer user types can set a developer fee and its optional
• Fees are deducted automatically during settlement

Status Tracking

Pay-ins move through the following lifecycle:

Status	Description
pending	Pay-in created, awaiting customer payment
confirmed	Funds detected and compliance checks passed
settling	Funds moving to the final destination
settled	Funds available to the recipient
payment_mismatch	Amount received does not match expected
failed	Expired or blocked by compliance

You can track status by:

• Polling the Payments Status API, or
• Subscribing to Webhooks

Magic Links & QR Codes

Celar provides Magic Links and QR Codes for customer payments.

• Both expose the same pay-in details
• Only available while the pay-in is pending or confirmed

Magic Link

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

QR Code

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

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.