Create a payin (top-up charge)

Corridor country. Required for every method except checkout, where it is optional and only preselects the payer's country on the page.

Corridor currency. Required for every method except checkout, which rejects it with 400 — the charge is denominated in settlement_asset.

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 returns a hosted payment_url for a 3-D Secure card checkout (Bolivia in BOB, or international cards in USD when country is US); 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.

Optional idempotency key (bank_transfer, fintoc, card and checkout methods; also accepted as the Idempotency-Key header). A retry with the same key returns the original payin with HTTP 200 and idempotency_hit: true — the same payment_url/checkout_url for hosted methods, or the SAME reference for an announced bank transfer — instead of opening a second charge. On announced transfers this decides whether the money can be credited: two live announcements with the same amount and no payer identity are indistinguishable, so the arriving deposit would stay unassigned. If you omit the key we still collapse an identical retry (same account, currency, amount and payer document) into the original announcement; send a distinct key when you really need two separate charges for the same amount and payer.

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).

Card method only — offer the payer a "save this card" checkbox on the hosted page. The credential is stored ONLY if the payer ticks it (explicit consent) and the 3-D Secure payment is approved; the payin_received/payin_credited flow then carries a stored_credential block and the card appears in GET /v1/stored-cards.

Card method only — your own identifier for the payer (e.g. your customer ID). Stored cards are scoped to this reference so you can list and charge the right customer's cards. Plain text, max 120 chars.

Card method only — pay with a previously saved card (see GET /v1/stored-cards). The hosted page skips card entry and shows the saved card; 3-D Secure still runs. Mutually exclusive with save_card. Unknown or revoked card responds 404. The billing details saved with the credential are applied automatically on the hosted page (masked summary with an edit link — the payer retypes nothing).

Announced bank transfer only — name of the person or company that will send the transfer, when it is NOT the account holder. Optional.

Announced bank transfer only — tax or national ID of the sender (at least 5 characters, one of them a digit). Optional: when you omit it the account holder's verified tax id is used, so a self-deposit is recognised even if the payer forgets the reference. Send it when a third party pays.

Announced bank transfer only — the sender's bank account number (at least 5 characters). Optional; it is an extra matching signal when the rail reports the originating account.