Skip to main content
POST
/
v1
/
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.

Maximum string length: 100

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.

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

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-1440).

Required range: 5 <= x <= 1440
​
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 the provider cannot enforce it, 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.

​
metadata
object

Arbitrary key-value pairs attached to the payment.

​
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.

​
card
object

Direct credit card charge payload. Allowed only for headless single-method CARD payments and required in that flow.

Response

Payment created.

​
payment
object
required