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": "Maria Silva",
    "email": "maria@example.com",
    "phone": "+5511999999999",
    "document": "12345678900"
  },
  "metadata": {
    "order_id": "1234",
    "source": "website"
  }
}
'
{
  "payment": {
    "id": "pay_abc123",
    "txId": "PAY_ABC123XYZ",
    "amount": 49.9,
    "feeAmount": 2.99,
    "netAmount": 46.91,
    "status": "NEW",
    "paymentMethod": "PIX",
    "currency": "BRL",
    "description": "Order #1234",
    "expiresAt": "2026-04-14T13:30:00.000Z",
    "createdAt": "2026-04-14T13:00:00.000Z",
    "methodData": {
      "type": "PIX",
      "pixCopyPaste": "00020126...",
      "qrCodeBase64": "data:image/png;base64,...",
      "qrCodeUrl": null
    }
  }
}

Authorizations

​
Authorization
string
header
required

API access token obtained from POST /oauth/token. Include as Authorization: Bearer {token}.

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

​
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