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
    }
  }
}

Changes

Changed in 6 of the 13 revisions of this API.51716

Aug 27, 20269d4ba1cc037c133See the full diff
- ▲
  the error response's property type/format changed from object/ to string/ for status 409
  response-property-type-changed
- ●
  removed the optional property error/code from the response with the 409 status
  response-optional-property-removed
- ●
  removed the optional property error/details from the response with the 409 status
  response-optional-property-removed
- ●
  removed the optional property error/message from the response with the 409 status
  response-optional-property-removed
- ○
  added the optional property code to the response with the 409 status
  response-optional-property-added
- ○
  added the optional property message to the response with the 409 status
  response-optional-property-added
- ○
  added the optional property statusCode to the response with the 409 status
  response-optional-property-added
Jul 12, 20260d036504e0492See the full diff
- ○
  added the new optional request property boleto
  new-optional-request-property
- ○
  the expiresInMinutes request property's max was increased from 1440.00 to 10080.00
  request-property-max-increased
Jun 7, 2026bb5bf9a209571See the full diff
- ○
  added the new optional request property enforcePayerDocument
  new-optional-request-property
May 10, 2026c1963c0f2a876See the full diff
- ○
  added the new optional request property passFeeToPayer
  new-optional-request-property
- ○
  added the optional property payment/oneOf[HeadlessPaymentCreateResponse]/feePassedToPayer to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property payment/oneOf[HeadlessPaymentCreateResponse]/isSandbox to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property payment/oneOf[HeadlessPaymentCreateResponse]/payerFeeAmount to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property payment/oneOf[HostedPaymentCreateResponse]/feePassedToPayer to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property payment/oneOf[HostedPaymentCreateResponse]/payerFeeAmount to the response with the 201 status
  response-optional-property-added
Apr 14, 202674ad5da44cf94143See the full diff
- ▲
  removed the enum value CRYPTO_LTC of the request property methods/items/
  request-property-enum-value-removed
- ▲
  removed the enum value LTC of the request property currency
  request-property-enum-value-removed
- ▲
  added HeadlessPaymentCreateResponse HostedPaymentCreateResponse to the payment response property oneOf list for the response status 201
  response-property-one-of-added
- ▲
  the payment response's property type/format changed from object/ to / for status 201
  response-property-type-changed
- ●
  removed the request property split
  request-property-removed
- ●
  removed the optional property payment/amount from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/createdAt from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/currency from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/description from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/expiresAt from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/feeAmount from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/id from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/metadata from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/methodData from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/netAmount from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/paymentMethod from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/status from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property payment/txId from the response with the 201 status
  response-optional-property-removed
- ○
  added the new optional request property card
  new-optional-request-property
- ○
  added the new optional request property customer/phone
  new-optional-request-property
- ○
  the response property payment became required for the status 201
  response-property-became-required
Apr 14, 2026c756571007571See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 8 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history