Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt

Use this file to discover all available pages before exploring further.

A payment is a charge against a payer for a fixed amount in BRL. YuvexPay exposes a single POST /v1/payments endpoint that creates payments across three methods (PIX, CARD, BOLETO) and two presentation modes (headless and hosted).

​
Methods at a glance

MethodHeadlessHosted
PIXReturns the BR-Code (copy-paste) and a QR code image. You render them in your own UI.Returns a checkoutUrl to the YuvexPay-hosted checkout.
CARDDirect charge: send card details server-side. Single-method, single-installment only.Multi-method or multi-installment card flows. The payer enters card details on YuvexPay’s hosted page.
BOLETOReturns a boleto barcode and a downloadable PDF.Available through the hosted checkout.
Pick headless when you want to render the payment yourself; pick hosted when you want YuvexPay to render the checkout, including method selection.

​
Amounts and currency

  • All amounts are in BRL as decimal numbers (e.g. 49.90), not cents.
  • The minimum chargeable amount is R$ 0.01. The maximum is R$ 1,000,000.00.
  • Card payments currently require installments: 1 (a single installment). Larger card transactions must be sent through the hosted multi-installment flow.

​
Identifiers

Every payment has two identifiers:
  • id — an internal UUID. Use it as the path parameter for GET /v1/payments/{paymentId} and POST /v1/payments/{paymentId}/refund.
  • txId — a stable, prefixed transaction id (PAY + 32 hex characters) that identifies the payment across logs, reports and the dashboard.
You can also pass externalId on creation — typically your own order id — which is stored on the payment for cross-referencing. externalId is unique per company and environment.

​
Lifecycle

NEW
  └── PROCESSING ──► CONFIRMED ──► PAID ──► PARTIAL_REFUND ──► REFUNDED
                                       │
                                       ├── CHARGEBACK
                                       └── MED_FROZEN
  └── PENDING_METHOD_SELECTION ──► (one of the above, after the payer picks a method)
  └── EXPIRED
  └── CANCELLED
StatusMeaning
NEWCreated and waiting for the payer.
PENDING_METHOD_SELECTIONA hosted multi-method checkout is created and the payer hasn’t picked a method yet.
PROCESSINGThe card or PIX network is processing the charge.
CONFIRMEDThe payment was authorized but funds are not yet settled (typical for cards/boleto).
PAIDFunds were received and credited to your balance.
EXPIREDThe payment window passed without payment.
CANCELLEDThe payment was cancelled before being paid.
PARTIAL_REFUNDA partial refund has been issued (currently only via inbound provider events).
REFUNDEDA full refund has been issued.
CHARGEBACKA chargeback was filed and processed.
MED_FROZENA PIX MED (special refund) is open; funds are temporarily held.
Listen for the corresponding webhook events to react to status changes asynchronously.

​
Headless PIX

Headless PIX is the simplest flow. Create the payment, render the QR code or copy-paste string, and listen for PAYMENT_PAID: 
curl -X POST https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer $YUVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-1234" \
  -d '{
    "amount": 49.90,
    "methods": ["PIX"],
    "currency": "BRL",
    "mode": "headless",
    "description": "Order #1234",
    "externalId": "order-1234",
    "expiresInMinutes": 30,
    "customer": {
      "name": "Pedro Álvares Cabral",
      "email": "user@example.com"
    }
  }'
The response includes methodData.pixCopyPaste (the BR-Code string) and methodData.qrCodeBase64 (a data URI). Render either to the payer.

​
Headless direct credit card

Direct card payments charge the card immediately on creation. The payer never leaves your UI, but you assume PCI scope: card data flows through your servers. 
{
  "amount": 149.90,
  "methods": ["CARD"],
  "currency": "BRL",
  "mode": "headless",
  "customer": {
    "name": "Pedro Álvares Cabral",
    "document": "12345678900",
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2030",
    "ccv": "123",
    "installments": 1,
    "remoteIp": "198.51.100.23",
    "holderInfo": {
      "postalCode": "01310930",
      "addressNumber": "100",
      "phone": "+5511999999999"
    }
  }
}
Direct card payments are constrained to methods: ["CARD"] (a single method), installments: 1, and require card.holderInfo and card.remoteIp. For multi-method or multi-installment card flows, use the hosted checkout.

​
Hosted checkout

Set mode: "hosted" to receive a checkoutUrl. Redirect the payer there; YuvexPay handles method selection, card capture and PIX rendering. 
{
  "amount": 49.90,
  "methods": ["PIX", "CARD"],
  "currency": "BRL",
  "mode": "hosted",
  "description": "Order #1234",
  "returnUrl": "https://store.example.com/checkout/return",
  "completionUrl": "https://store.example.com/checkout/done",
  "customer": {
    "name": "Pedro Álvares Cabral",
    "email": "user@example.com"
  }
}
  • returnUrl is where YuvexPay sends the payer if they abandon the checkout.
  • completionUrl is where YuvexPay redirects after a successful payment.
Hosted payments start in PENDING_METHOD_SELECTION until the payer picks a method, then transition through the same lifecycle as a headless payment.

​
Fees and net amount

Each payment response includes:
  • amount — the gross amount charged to the payer.
  • feeAmount — the YuvexPay processing fee.
  • netAmount — the amount credited to your balance once the payment settles.
Fees are computed at creation time using the merchant’s configured rate. passFeeToPayer: true shifts the fee onto the payer (the payer is charged amount + feeAmount); when false, the fee is deducted from amount.

​
Pagination and filtering

GET /v1/payments supports the standard page (default 1) and limit (default 20, max 100) parameters along with these filters:
  • status — filter by PaymentStatus.
  • method — filter by PIX, CARD or BOLETO.
  • startDate / endDate — ISO 8601 date or date-time bounds.
  • minAmount / maxAmount — decimal BRL bounds.
  • environment — SANDBOX or PRODUCTION (defaults to the API key’s environment).

​
Receipts

Once a payment is PAID or REFUNDED, you can fetch a printable receipt: 
GET /v1/documents/payments/{paymentId}/receipt?format=html
See the Documents reference for the full response shape.