Quickstart

1. Get your API key

Log in to the YuvexPay dashboard and navigate to Desenvolvedores > Chaves de API (Developers > API keys). Create a new key, choose Sandbox for testing, and copy the full secret — the secret is shown only once.

Treat API keys like database credentials. Store them in a secrets manager or environment variable, never in source control or client-side code. If a key leaks, revoke it from the dashboard and rotate.

Test keys are prefixed with ypk_test_ and only access sandbox data. Production keys are prefixed with ypk_live_. A key looks like ypk_<env>_<kid>_<secret>; the <kid> part is a 10-character public key id (safe to log) and the <secret> part is the 32-character private material (never log it).

Each key is scoped to a single company and carries one or more permissions (payments:write, payments:read, payments:refund, withdrawals:write, withdrawals:read, customers:write, customers:read, products:write, products:read, documents:read, webhooks:read). Choose the smallest set of scopes the integration needs.

2. Create a payment

Authenticate each request with your API key as a Bearer token. All write endpoints require an X-Idempotency-Key header so retries never double-charge a customer.

curl -X POST https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-1234-attempt-1" \
  -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"
    }
  }'

const response = await fetch("https://api.yuvexpay.com/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.YUVEX_API_KEY}`,
    "Content-Type": "application/json",
    "X-Idempotency-Key": "order-1234-attempt-1",
  },
  body: JSON.stringify({
    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",
    },
  }),
});

const { payment } = await response.json();

import os
import requests

response = requests.post(
    "https://api.yuvexpay.com/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['YUVEX_API_KEY']}",
        "X-Idempotency-Key": "order-1234-attempt-1",
    },
    json={
        "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",
        },
    },
)

payment = response.json()["payment"]

The response contains the payment record with method-specific data:

{
  "payment": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "txId": "PAY3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c",
    "amount": 49.90,
    "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
    }
  }
}

Render pixCopyPaste as a copy-paste string and qrCodeBase64 as a QR code image. Use id as the path parameter for follow-up calls (GET /v1/payments/{paymentId}, POST /v1/payments/{paymentId}/refund). To accept a card, create the payment with mode: "hosted" and CARD in methods, and send the payer to the returned checkoutUrl: see Card payments.

3. Listen for webhooks

Set up a webhook endpoint to receive payment notifications. Configure it in the dashboard under Desenvolvedores > Webhooks (Developers > Webhooks). When the customer pays, your endpoint receives a POST whose X-Webhook-Event header is PAYMENT_PAID. The body is the event itself — there is no envelope, and the event name is not in the body:

{
  "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
  "txId": "PAY3F2A8B9C4E6D1F5A7B3C8D2E9F4A6B1C",
  "status": "PAID",
  "amount": 49.9,
  "paidAt": "2026-06-06T12:00:00.000Z",
  "endToEndId": "E000000022026060612000abc1234def",
  "payer": {
    "name": "Maria Silva",
    "document": "39053344705",
    "documentType": "CPF",
    "institutionName": "Banco Example S.A.",
    "institutionIspb": "00000000"
  }
}

Switch on X-Webhook-Event, and always verify the webhook signature before acting on the event.

Webhook guide

Learn how to verify signatures, handle retries and dedupe events.

Next steps

Payments guide

PIX, card and boleto in detail.

Refunds

Refund eligibility, lifecycle and error codes.

Withdrawals

Move BRL from your balance via PIX.

Sandbox

Deterministic recipes for testing.

Getting started

Core concepts

Products

1. Get your API key

2. Create a payment

3. Listen for webhooks

Webhook guide

Next steps

Payments guide

Refunds

Withdrawals

Sandbox

​1. Get your API key

​2. Create a payment

​3. Listen for webhooks

Webhook guide

​Next steps

Payments guide

Refunds

Withdrawals

Sandbox

1. Get your API key

2. Create a payment

3. Listen for webhooks

Next steps