Sign in

v10

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-122928103.7 KB
Payments

Create a payment

Create a new payment. Supports PIX, direct credit card charges for headless single-method CARD flows, hosted card checkout, and boleto. Requires an idempotency key.

post/v1/payments

Headers

X-Idempotency-Keystring required

A unique string to ensure the request is processed only once. Must be unique per request. Valid for 24 hours.

Request body

productIdstring uuid

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

customerIdstring uuid

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

amountnumber

Payment amount. Required unless productId is provided.

methodsPaymentMethod[]

Accepted payment methods. Headless payments must use exactly one method.

currency'BRL'

Supported currencies.

mode'hosted' | 'headless'

hosted redirects the payer to a YuvexPay checkout page. headless returns method data directly for a single payment method. Headless CARD requires the card payload for direct credit card capture. Hosted or multi-method CARD flows continue through checkout/provider invoice URLs, where debit remains available.

returnUrlstring uri

URL to redirect the payer after payment (hosted mode).

completionUrlstring uri

URL to redirect the payer after successful payment completion.

descriptionstring

Payment description shown to the payer.

externalIdstring

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

expiresInMinutesinteger

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

enforcePayerDocumentboolean

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 the provider cannot enforce it, the charge is still created and paid normally.

metadataobject

Arbitrary key-value pairs attached to the payment.

passFeeToPayerboolean

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.

Response

Payment created.

Example response

{
  "payment": {
    "methodData": {
      "type": "CARD",
      "captureType": "DIRECT",
      "cardSubtype": "CREDIT",
      "brand": "VISA",
      "last4Digits": "1111",
      "installments": 1
    }
  }
}