Skip to main content

​
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"
    }
  }'
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.