> ## 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.

# API reference

> Complete reference for the YuvexPay REST API.

The YuvexPay API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes and verbs.

## Base URL

```
https://api.yuvexpay.com
```

All API requests must be made over HTTPS. The same URL serves both sandbox and
production — the environment is determined by which API key you send. Sandbox
keys are prefixed with `ypk_test_`, production keys with `ypk_live_`.

## Authentication

All `/v1/*` endpoints authenticate with an **API key** sent as a Bearer token.
Create keys in the dashboard under **Settings > API Keys**:

```bash theme={null}
Authorization: Bearer ypk_<env>_<kid>_<secret>
```

See the [authentication guide](/guides/authentication) for the full key format,
scopes and rotation workflow. To inspect the key being used, call
[`GET /v1/auth/self`](/api-reference/auth/self).

## Request headers

| Header              | Required         | Description                                                          |
| ------------------- | ---------------- | -------------------------------------------------------------------- |
| `Authorization`     | Yes              | `Bearer ypk_<env>_<kid>_<secret>` — your API key.                    |
| `Content-Type`      | Yes (POST/PATCH) | `application/json`                                                   |
| `X-Idempotency-Key` | Yes (write POST) | Unique key for safe retries. See [idempotency](/guides/idempotency). |

## Response envelope

Successful responses are JSON objects keyed by the resource (`{ "payment": {...} }`,
`{ "withdrawal": {...} }`, etc.). List responses include a `pagination` block:

```json theme={null}
{
  "payments": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}
```

Errors follow a consistent envelope. See the [errors guide](/guides/errors)
for codes and handling patterns.

## Resources

<Columns cols={2}>
  <Card title="Payments" icon="credit-card" href="/api-reference/payments/create">
    Create and manage payments via PIX, direct card charges, hosted card checkout, or boleto.
  </Card>

  <Card title="Withdrawals" icon="money-bill-transfer" href="/api-reference/withdrawals/create">
    Transfer BRL funds from your balance via PIX.
  </Card>

  <Card title="Products" icon="box" href="/api-reference/products/create">
    Manage your product catalog.
  </Card>

  <Card title="Customers" icon="users" href="/api-reference/customers/create">
    Store and manage customer records.
  </Card>

  <Card title="Documents" icon="file-lines" href="/api-reference/documents/payment-receipt">
    Generate receipts and account statements.
  </Card>

  <Card title="Balance" icon="wallet" href="/api-reference/balance/get">
    Read the company's available, frozen, held, and total balance.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/auth/self">
    Inspect the API key currently in use.
  </Card>
</Columns>