Create a payin (top-up charge)
Creates a fiat top-up. With method: "qr" (default) an active QR charge is generated through the processor — in Bolivia the local interoperable QR, in Brazil a dynamic PIX QR whose charge carries the QR image and the “copia e cola” payload. With method: "bank_transfer" the deposit is announced and the response carries the reference the sender must include so the arriving transfer is matched and credited automatically — a short 12-character alphanumeric code that fits any bank concept field (some rails cap it at 20 characters with no special characters). With method: "fintoc" (Chile) the response carries a hosted payment_url: the payer opens it and transfers from any Chilean bank or wallet; the deposit is detected, validated and credited automatically. With method: "card" (Bolivia) the response carries a hosted payment_url for a 3-D Secure card checkout branded with your organization — card data never touches your integration. With method: "checkout" the response carries a public checkout_url — a branded universal checkout link denominated in the virtual balance of your choice (settlement_asset: USDT, USDC, BTC or GOLD). The payer picks any country with a live payin corridor (quoted local amount), any of the 4 crypto options (exclusive deposit address with a scannable QR), or pays instantly from the CBPay app via the merchant QR/alias; every payment is auto-converted to the settlement asset unless paid in the same asset. The first method that completes the payment wins. Charging is free; the payin fee applies when the deposit is credited.
Authorizations
Session JWT (from register/login) or API key (pk_...).
X-API-Key: <token> is accepted as an alternative header.
Body
Corridor country. Required for every method except checkout, where it is optional and only preselects the payer's country on the page.
"BO"
Corridor currency. Required for every method except checkout, which rejects it with 400 — the charge is denominated in settlement_asset.
"BOB"
Positive decimal string. Local currency amount for corridor methods; for checkout it is denominated in the settlement_asset ("50" USDT, "0.001" BTC, "2" grams of gold).
Optional channel hint passed to the core.
Charge expiration in seconds. For checkout it accepts 600 to 604800 (10 minutes to 7 days; default 24 hours).
Collection mode. qr creates an active QR charge through the processor; bank_transfer announces an incoming deposit and returns the reference to include in the transfer description; fintoc (Chile only) returns a hosted payment_url where the payer transfers from any Chilean bank or wallet and the deposit is detected automatically; card (Bolivia) returns a hosted payment_url for a 3-D Secure card checkout; checkout returns a public checkout_url where the payer picks the payment method (QR, card, bank transfer or crypto). Use /v1/payins/collect for pull collections.
qr, bank_transfer, fintoc, card, checkout Optional idempotency key (fintoc, card and checkout methods; also accepted as the Idempotency-Key header). A retry with the same key returns the original payin and its payment_url/checkout_url instead of opening a second payment session.
Optional billing prefill for the card checkout (card method) — email, first_name, last_name, address, city, country (plain text, max 120 chars per field). The payer can complete or correct them on the page.
Optional public https URL (card and checkout methods) the payer is redirected to after an approved payment.
Optional public https URL (card and checkout methods) the payer is redirected to when the payment fails or expires.
Optional RFC3339 expiry for the card payment session (card method, at least 15 minutes ahead; default 24 hours).
Checkout only — the virtual balance the charge is denominated in and settles into. Every payment is auto-converted to this asset on credit (same-asset payments skip conversion). Must be enabled for your organization (422 settlement_asset_disabled otherwise).
USDT, USDC, BTC, GOLD