> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create your first payment with the YuvexPay API in under 5 minutes.
## 1. Get your API key
Log in to the [YuvexPay dashboard](https://app.yuvexpay.com) 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___`; the `` part is a 10-character public key id
(safe to log) and the `` 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.
```bash cURL theme={null}
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"
}
}'
```
```javascript Node.js theme={null}
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();
```
```python Python theme={null}
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:
```json theme={null}
{
"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`.
```json theme={null}
{
"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:
```json theme={null}
{
"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](/guides/webhooks#verifying-signatures)
before acting on the event.
Learn how to verify signatures, handle retries and dedupe events.
## Next steps
PIX, card and boleto in detail.
Refund eligibility, lifecycle and error codes.
Move BRL from your balance via PIX.
Deterministic recipes for testing.