Create a payment

Link this payment to an existing product. If set, amount is optional and defaults to the product price.

Link this payment to an existing customer. For CARD and BOLETO, the linked customer must have name and CPF/CNPJ.

Payment amount. Required unless productId or items is provided. With items it can be omitted; when sent, it must equal the sum of unitAmount x quantity exactly (400 AMOUNT_ITEMS_MISMATCH).

Supported currencies.

hosted redirects the payer to a YuvexPay checkout page. headless returns method data directly for a single payment method, PIX or BOLETO. CARD is available in hosted mode only: the YuvexPay checkout collects the card, accepts credit cards in a single installment and debit cards, and runs 3D Secure itself.

Hosted mode: the back link the checkout shows while the payment is unpaid, for a payer who leaves without paying. Only an http or https URL of up to 2048 characters is used; metadata.cancelUrl takes precedence. Use completionUrl for the redirect after payment.

Hosted mode: where the checkout sends the payer, after a 5-second countdown, once the payment is PAID, CONFIRMED or FREE. The checkout adds yvx_payment_id, yvx_status, yvx_amount_cents, yvx_reference, yvx_ts and yvx_signature, a lowercase hex HMAC-SHA256 of payment_id.status.amount_cents.reference.ts keyed with the account's redirect secret; see the payments guide to verify it. While a post-purchase upsell is offered, the checkout shows a button to this URL instead of the countdown. Only an http or https URL of up to 2048 characters is used. The redirect is not proof of payment: confirm with GET /v1/payments/{paymentId} or the webhook before fulfilling.

Payment description shown to the payer.

Your own reference ID (e.g., order number).

Minutes until the payment expires (5-10080, i.e. up to 7 days).

PIX only. Opt-in request that the charge be paid from an account whose CPF/CNPJ matches the customer's document (same-document payment). Best-effort: when it cannot be enforced, the charge is still created and paid normally.

Whether the YuvexPay fee should be added on top of amount and charged to the payer instead of being deducted from the merchant's net. When omitted, the company-level passFeeToPayerDefault setting applies. Note: payments with a resolved amount below R$1,00 are always charged to the payer regardless of this value (forced passthrough to keep merchant net positive). The final decision is reflected back as feePassedToPayer on the Payment object. On a hosted payment the fee is computed again, at the rate of the method the payer picks, card included; the checkout shows each method with its own total. A payment that completes as FREE never passes a fee.

Turn the recovery kit on (true) or off (false) for this payment. When omitted, the account default applies (Ativar por padrão on the Kit de recuperação card in the dashboard, off until turned on). The kit e-mails a payer who filled in the hosted checkout and did not pay: up to 5 e-mails at the delays set for the account, 15 minutes, 1 hour and 24 hours unless changed, plus one about 10 minutes before a PIX code expires, sent only while the payment can still be paid. It starts when the hosted checkout saves the payer's details, or when the checkout is first opened for a payment whose customer already has them, so it does nothing on a headless payment. The kit price, shown in the dashboard, is debited once, when the first e-mail is sent, even if the balance goes negative. Sandbox payments never get a kit: recoveryKit.enabled is false on them. The result is returned as recoveryKit on the Payment object.

Let the payer change the quantity of each line on the hosted checkout before picking a method; the amount, the coupon discount, the fee and percentage splits are computed again. Ignored without items and on a payment with a FIXED split.

Coupon to apply, case-insensitive. A code that does not exist, is inactive, outside its validity window, out of uses, over the per-payer limit for customer.email, gives no discount on this order, or is sent with a FIXED split returns 400 COUPON_INVALID, one answer for every reason. A discount of the whole amount completes the payment as FREE: at once for a headless payment, when the payer confirms on the hosted checkout.