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; pix (Brazil only) returns a hosted payment_url for a PIX redirect checkout (payer_name and payer_document required, minimum 1 BRL); 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. wallet is hosted or collect-only depending on the corridor; collect-only flows do not return a payment URL.

For method: "card", this key is required; send it in the body or as the Idempotency-Key header. It is optional for qr, bank_transfer, fintoc, pix and checkout methods. 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 5 minutes ahead and no more than 48 hours from creation. Default 60 minutes.

Checkout only — the virtual balance the charge is denominated in and settles into. When omitted it resolves to your payin_settlement_asset (USD is the principal balance). Every payment is auto-converted to this asset on credit (same-asset payments skip conversion). Local fiat (BOB, MXN, ARS) is rejected. 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 plain-text identifier for the payer (max 120 chars). It is the preferred identity for reusing an open pending/challenge card session; when absent, customer.email is used as the fallback. It scopes stored-card discovery and charges within the calling account; the same email or reference in another account cannot discover or use the credential.

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, including a credential from another account, 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).

Payer identity. Required for pix (Brazil hosted redirect); for announced bank transfers it is the optional name of the person or company that will send the transfer, when it is NOT the account holder.

Payer identity. Required for pix (Brazil hosted redirect); for announced bank transfers it is the optional tax or national ID of the sender (at least 5 characters, one of them a digit): 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.

Hosted or collect payer phone; required by some wallet methods.

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.