Payments

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

Method	Headless	Hosted
`PIX`	Returns 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.
`CARD`	Direct 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.
`BOLETO`	Returns 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

Status	Meaning
`NEW`	Created and waiting for the payer.
`PENDING_METHOD_SELECTION`	A hosted multi-method checkout is created and the payer hasn’t picked a method yet.
`PROCESSING`	The card or PIX network is processing the charge.
`CONFIRMED`	The payment was authorized but funds are not yet settled (typical for cards/boleto).
`PAID`	Funds were received and credited to your balance.
`EXPIRED`	The payment window passed without payment.
`CANCELLED`	The payment was cancelled before being paid.
`PARTIAL_REFUND`	A partial refund has been issued and part of the payment is still refundable.
`REFUNDED`	A full refund has been issued.
`CHARGEBACK`	A chargeback was filed and processed.
`MED_FROZEN`	A 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, before any splits.

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.

Splits

A payment can hand part of itself to other YuvexPay companies. Send splits on POST /v1/payments; each entry names the company that receives a share and how much of the payment it gets.

{
  "amount": 49.90,
  "methods": ["PIX"],
  "mode": "headless",
  "splits": [
    {
      "recipientCompanyId": "b7f1c3d2-4e5a-4b6c-8d9e-0a1b2c3d4e5f",
      "type": "PERCENTAGE",
      "value": 10
    },
    {
      "recipientCompanyId": "c9a2d4e6-8b1f-4c3a-9d7e-2f5a8b0c1d3e",
      "type": "FIXED",
      "value": 5.00
    }
  ]
}

Field	Value	Meaning
`recipientCompanyId`	uuid	The YuvexPay company that receives the share. Must be a company other than your own, and unique within the array.
`type`	`PERCENTAGE` or `FIXED`	How `value` is read. Both forms can coexist in the same array.
`value`	`0.01`–`100` for `PERCENTAGE`; `0.01` or more for `FIXED`	A percentage of `amount`, or a BRL amount. At most two decimal places either way.

splits is optional. The maximum number of entries is the recipient limit configured for your account — three by default, and support can raise it. Splits are set at creation only: there is no endpoint to add, edit or remove one afterwards. The create response and the payment detail response echo them back as splits, each entry carrying an id alongside the three fields you sent, and [] when the payment has none.

How the money divides

The YuvexPay fee is always the originating company’s and is never apportioned. Shares are computed from amount — the gross — and the fee comes out of your share alone. When passFeeToPayer is true, nothing is deducted from amount at all. netAmount stays pre-split: it is still amount - feeAmount, or amount when the fee is passed to the payer. You keep netAmount minus the sum of the splits, and the recipients are credited when the payment settles. For amount: 49.90 against a 2.99 fee, split 10% to one company and a fixed R$ 5.00 to another:

Field	Value	Meaning
`amount`	`49.90`	The gross. Percentage shares are computed from it.
`feeAmount`	`2.99`	Yours. Never apportioned.
`netAmount`	`46.91`	`amount - feeAmount`, before splits.
First split (`PERCENTAGE`, `10`)	`4.99`	10% of `49.90`.
Second split (`FIXED`, `5.00`)	`5.00`	Taken as sent.
Your share	`36.92`	`netAmount` minus both splits.

The sum of the splits must be at most netAmount. A request that goes over fails with SPLIT_AMOUNT_EXCEEDS_NET and the response names the overflow. Nothing is clamped. Percentage shares are rounded down to the cent, and every remaining cent stays with the originating company. On amount: 100.00 with a 2.99 fee and one recipient at 33.33%, the recipient is credited 33.33 and you keep 97.01 - 33.33 = 63.68.

Opting in

The first time you split to a company, that company has to accept the relationship in its dashboard. Until it does, creating the payment fails with SPLIT_RELATIONSHIP_PENDING. Once it has accepted, later payments carry no further friction. SPLIT_RELATIONSHIP_PENDING is the single answer for every recipient that cannot receive a split yet. It reads the same whether the company ID belongs to a real company or to no company at all, so the error cannot be used to discover which company IDs exist. A consent request is created only for a recipient that does exist, is active, is in the same environment and is approved. Your company can hold a limited number of split requests awaiting an answer, 20 by default and counted per environment. Beyond that, naming a new recipient fails with SPLIT_RELATIONSHIP_REQUEST_LIMIT until some of the outstanding requests are answered. The recipient can revoke at any time. New payments then fail with SPLIT_RELATIONSHIP_REVOKED.

Revocation is forward-only. Payments that were already created still settle, refund and freeze normally, and the recipient still receives those shares.

Both companies must be approved before a split payment can be created: KYC for an individual, KYC and KYB for a business, on both sides. The check runs when the payment is created, not when it settles. Your own company failing it returns 403 SPLIT_ORIGINATOR_NOT_APPROVED. A recipient that has not accepted yet returns SPLIT_RELATIONSHIP_PENDING whatever the reason; one that had accepted and has since stopped meeting the bar returns SPLIT_RECIPIENT_NOT_APPROVED.

What a recipient sees

A split is not the recipient’s payment, and recipients get no webhook and no receipt for it.

GET /v1/payments/{paymentId} returns 404 for a recipient: the payment belongs to the originating company.
The payment receipt is originator-only.
Recipients see the money in GET /v1/balance and in GET /v1/documents/statements, and in their dashboard.

Don’t build a recipient integration that waits for PAYMENT_PAID. No webhook is delivered to a recipient for a split. Read the balance or the statement instead.

Refunds, MED and reserve

Refunds and PIX MED are proportional. A refund debits every party in proportion to what it received, the originating company included, and partial refunds use the same proportions. A MED freezes each party’s proportional share. A recipient that has already withdrawn its share goes negative. The shortfall is never moved onto the originating company, and INSUFFICIENT_BALANCE_FOR_REFUND is measured against the originating company’s share only. A split credit is subject to the recipient’s own rolling reserve policy, not the originator’s. When a refund or MED debit lands on a recipient whose share is still in reserve, that payment’s own reserve hold is released first and the debit is written against it.

Sandbox and anticipation

A sandbox payment can only split to a company that is in sandbox mode, and a production payment only to a production company. The other direction is always rejected, never a silent no-op: 400 SPLIT_RELATIONSHIP_PENDING for a recipient that has not accepted in this environment, and 400 SPLIT_ENVIRONMENT_MISMATCH for one that had. Sandbox splits never touch a production balance, statement or report. Payments that carry splits cannot be anticipated (ANTICIPATION_SPLIT_PAYMENT).

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.

Getting started

Core concepts

Products

Methods at a glance

Amounts and currency

Identifiers

Lifecycle

Headless PIX

Headless direct credit card

Hosted checkout

Fees and net amount

Splits

How the money divides

Opting in

What a recipient sees

Refunds, MED and reserve

Sandbox and anticipation

Receipts

​Methods at a glance

​Amounts and currency

​Identifiers

​Lifecycle

​Headless PIX

​Headless direct credit card

​Hosted checkout

​Fees and net amount

​Splits

​How the money divides

​Opting in

​What a recipient sees

​Refunds, MED and reserve

​Sandbox and anticipation

​Pagination and filtering

​Receipts

Methods at a glance

Amounts and currency

Identifiers

Lifecycle

Headless PIX

Headless direct credit card

Hosted checkout

Fees and net amount

Splits

How the money divides

Opting in

What a recipient sees

Refunds, MED and reserve

Sandbox and anticipation

Pagination and filtering

Receipts