curl --request POST \
  --url https://api.yuvexpay.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "amount": 49.9,
  "methods": [
    "PIX"
  ],
  "currency": "BRL",
  "mode": "headless",
  "description": "Order #1234",
  "externalId": "order-1234",
  "expiresInMinutes": 30,
  "customer": {
    "name": "Pedro Álvares Cabral",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "document": "12345678900"
  },
  "metadata": {
    "order_id": "1234",
    "source": "website"
  }
}
'

{
  "payment": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "txId": "PAY3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c",
    "amount": 49.9,
    "feeAmount": 2.99,
    "netAmount": 46.91,
    "status": "NEW",
    "paymentMethod": "PIX",
    "currency": "BRL",
    "description": "Order #1234",
    "expiresAt": "2026-05-03T15:00:00.000Z",
    "createdAt": "2026-05-03T14:30:00.000Z",
    "methodData": {
      "type": "PIX",
      "pixCopyPaste": "00020126...",
      "qrCodeBase64": "data:image/png;base64,...",
      "qrCodeUrl": null
    }
  }
}

Payments

Create a payment

Create a new payment. Supports PIX and boleto, in headless or hosted mode, and card through the hosted checkout only. Requires an idempotency key.

Card payments are not accepted through the API. A card object, CARD in methods in headless mode (mode omitted or headless), or any of these fields at the top level of the body: deviceInfo, remoteIp, holderInfo, authorizeOnly, creditCard, creditCardHolderInfo, creditCardToken, installmentCount, installmentValue, totalValue, is rejected with 400 CARD_PAYMENTS_NOT_AVAILABLE_VIA_API, even without a valid API key, and the card data is not stored or logged.

To charge a card, create the payment with mode: hosted and CARD in methods (["CARD"], or ["PIX", "CARD"] to let the payer choose), with an amount of at least R$ 5.00, and redirect the payer to the returned checkoutUrl. The checkout collects the card, accepts credit cards in a single installment and debit cards, and runs 3D Secure itself. The result arrives as PAYMENT_CONFIRMED, PAYMENT_PAID, PAYMENT_EXPIRED or PAYMENT_CANCELLED; you can also poll GET /v1/payments/{paymentId}.

POST

payments

curl --request POST \
  --url https://api.yuvexpay.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "amount": 49.9,
  "methods": [
    "PIX"
  ],
  "currency": "BRL",
  "mode": "headless",
  "description": "Order #1234",
  "externalId": "order-1234",
  "expiresInMinutes": 30,
  "customer": {
    "name": "Pedro Álvares Cabral",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "document": "12345678900"
  },
  "metadata": {
    "order_id": "1234",
    "source": "website"
  }
}
'

{
  "payment": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "txId": "PAY3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c",
    "amount": 49.9,
    "feeAmount": 2.99,
    "netAmount": 46.91,
    "status": "NEW",
    "paymentMethod": "PIX",
    "currency": "BRL",
    "description": "Order #1234",
    "expiresAt": "2026-05-03T15:00:00.000Z",
    "createdAt": "2026-05-03T14:30:00.000Z",
    "methodData": {
      "type": "PIX",
      "pixCopyPaste": "00020126...",
      "qrCodeBase64": "data:image/png;base64,...",
      "qrCodeUrl": null
    }
  }
}

Authorizations

Authorization

string

header

required

YuvexPay API key. Include as Authorization: Bearer ypk_<env>_<kid>_<secret> where <env> is test (sandbox) or live (production). Create and manage keys in the dashboard under Settings > API Keys.

Headers

X-Idempotency-Key

string

required

A unique string to ensure the request is processed only once. Must be unique per request. Valid for 24 hours. Successful (2xx) responses are stored and replayed for the key. On POST /v1/payments, a 502 PROVIDER_TEMPORARILY_UNAVAILABLE for a boleto payment is stored and replayed too: to recover that payment, repeat the request once with the same externalId and a new key. A retry of an earlier card payment request now returns 400 CARD_PAYMENTS_NOT_AVAILABLE_VIA_API instead of the stored response (201 or 502): recover that payment with GET /v1/payments/txid/{txId}, or with a create request with the same externalId, mode: "hosted" and methods: ["CARD"], no card object or card fields, and a new key.

Maximum string length: 100

X-Split-Platform-Key

string

API key of an approved split platform, sent as the key itself, without Bearer, in the environment of the key in Authorization: ypk_live_ in production, ypk_test_ in sandbox. It lets the platform named in splits[] connect the seller on this call, with no dashboard invitation: the relationship is recorded as ACCEPTED with the platform's fee cap and the payment is created. The connection works in production and in sandbox under the same fee cap, and only a production connection notifies the seller. The header is read only when exactly one recipient in splits[] has no accepted relationship with your company, and ignored otherwise. A key that is unknown, revoked or expired, is from the other environment, lacks the payments:write scope, is used from outside its IP allowlist or belongs to your own company returns 403 SPLIT_PLATFORM_KEY_INVALID. A valid key whose company is not that recipient, or is not an approved platform, connects nobody: the request follows the regular flow and returns SPLIT_RELATIONSHIP_PENDING. Send it from a server only. See the Split platforms guide.

Body

application/json

productId

string<uuid>

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

customerId

string<uuid>

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

amount

number

Payment amount. Required unless productId is provided.

Required range: 0.01 <= x <= 1000000

methods

enum<string>[]

Accepted payment methods. Headless payments must use exactly one method, PIX or BOLETO. CARD requires mode: hosted; headless CARD is rejected with 400 CARD_PAYMENTS_NOT_AVAILABLE_VIA_API.

Minimum array length: 1

Available public payment methods.

Available options:

PIX,

CARD,

BOLETO

currency

enum<string>

default:BRL

Supported currencies.

Available options:

BRL

mode

enum<string>

default:headless

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.

Available options:

hosted,

headless

returnUrl

string<uri>

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

completionUrl

string<uri>

URL to redirect the payer after successful payment completion.

description

string

Payment description shown to the payer.

Maximum string length: 500

externalId

string

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

Maximum string length: 100

expiresInMinutes

integer

default:60

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

Required range: 5 <= x <= 10080

enforcePayerDocument

boolean

default:false

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.

customer

object

Inline customer data. For CARD and BOLETO, include at least name and CPF/CNPJ unless you use customerId.

Show child attributes

metadata

object

Arbitrary key-value pairs attached to the payment.

Show child attributes

passFeeToPayer

boolean

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.

splits

object[]

Share part of this payment with other YuvexPay companies when it settles. Optional. The maximum number of entries is the recipient limit configured for your account — three by default, and support can raise it; going over it returns SPLIT_RECIPIENT_LIMIT_EXCEEDED. The sum of the splits must not exceed netAmount, otherwise the request fails with SPLIT_AMOUNT_EXCEEDS_NET and nothing is clamped. The YuvexPay fee is always yours and is never apportioned. Splits are set only at creation: there is no endpoint to add, edit or remove one afterwards.

Show child attributes

boleto

object

Boleto-specific options, applied only when BOLETO is one of the methods. Fine, interest, and discount mirror the boleto configuration registered with the bank and are settled against the amount the payer actually pays.

Show child attributes

Response

Payment created.

payment

object

required

Option 1
Option 2

Show child attributes

Overview

Authentication

Payments

Withdrawals

Balance

Splits

Products

Customers

Documents

Public

Create a payment

Authorizations

Headers

Body

Response