Skip to main content

​
1. Get your API credentials

Log in to the YuvexPay dashboard and navigate to Settings > API Credentials. Create a new credential pair to get your client_id and client_secret.
Start with sandbox credentials to test without processing real transactions. Sandbox client_secret values are prefixed with sk_sandbox_, while access tokens are prefixed with ypt_.

​
2. Generate an access token

Exchange your credentials for an access token: 
curl -X POST https://api.yuvexpay.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'
The response includes an access_token valid for 1 hour: 
{
  "access_token": "ypt_abc123example",
  "token_type": "Bearer",
  "expires_in": 3600,
  "company_id": "comp_abc123",
  "company_name": "My Store"
}

​
3. Create a payment

Use the token to create a PIX payment: 
curl -X POST https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer ypt_abc123example" \
  -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": "Maria Silva",
      "email": "maria@example.com"
    }
  }'
The response contains the payment details with method-specific data: 
{
  "payment": {
    "id": "pay_abc123",
    "txId": "PAY_ABC123XYZ",
    "amount": 49.9,
    "feeAmount": 2.99,
    "netAmount": 46.91,
    "status": "NEW",
    "paymentMethod": "PIX",
    "currency": "BRL",
    "description": "Order #1234",
    "expiresAt": "2026-04-14T13:30:00.000Z",
    "createdAt": "2026-04-14T13:00:00.000Z",
    "methodData": {
      "type": "PIX",
      "pixCopyPaste": "00020126...",
      "qrCodeBase64": "data:image/png;base64,...",
      "qrCodeUrl": null
    }
  }
}

​
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.9,
  "methods": ["CARD"],
  "currency": "BRL",
  "mode": "headless",
  "customer": {
    "name": "Maria Silva",
    "document": "12345678900",
    "email": "maria@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. Hosted and multi-method card flows continue through checkout, and debit card entry stays in the hosted flow.

​
4. 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": "pay_abc123",
    "txId": "YVX-20260414-ABC",
    "status": "PAID",
    "amount": 49.90
  }
}

Webhook guide

Learn how to verify webhook signatures and handle all event types.

​
Next steps

API reference

Explore all available endpoints.

Webhooks

Set up real-time event notifications.

Error handling

Handle errors and edge cases.

Environments

Understand sandbox vs. production.