Quickstart

1. Get your API key

Log in to the YuvexPay dashboard and navigate to Settings > 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).

Direct credit card charges

For headless direct credit card charges, send a single CARD method together with the card payload. The payer must have name and document available through customer or customerId.

{
  "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"
    }
  }
}

card is only accepted for headless single-method CARD payments with installments: 1. Hosted and multi-installment card flows go through the hosted checkout.

3. Listen for webhooks

Set up a webhook endpoint to receive payment notifications. Configure it in the dashboard under Settings > Webhooks. When the customer pays, you receive a PAYMENT_PAID event:

{
  "id": "evt_xyz789",
  "type": "PAYMENT_PAID",
  "data": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "txId": "PAY3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c",
    "status": "PAID",
    "amount": 49.90
  }
}

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

Direct credit card charges

3. Listen for webhooks

Webhook guide

Next steps

Payments guide

Refunds

Withdrawals

Sandbox

​1. Get your API key

​2. Create a payment

​Direct credit card charges

​3. Listen for webhooks

Webhook guide

​Next steps

Payments guide

Refunds

Withdrawals

Sandbox

1. Get your API key

2. Create a payment

Direct credit card charges

3. Listen for webhooks

Next steps