Authentication

All requests to /v1/* endpoints are authenticated with an API key sent as a Bearer token in the Authorization header. There is no separate token exchange — the key itself is the credential.

Creating an API key

Log in to the YuvexPay dashboard.
Open Settings > API Keys.
Click Create key, choose the environment (sandbox or production) and pick the scopes the integration needs (see below).
Copy the key — it is shown only once at creation.

The key secret is shown only once. Store it in a secrets manager or environment variable (YUVEX_API_KEY). If it leaks, revoke it from the dashboard and create a new one.

Key format

A full key has the shape:

ypk_<env>_<kid>_<secret>

ypk — fixed prefix.
<env> — test for sandbox, live for production.
<kid> — the public key id (10 characters). Safe to log; we also show it in the dashboard so you can identify which key was used.
<secret> — the private material (32 characters). Never log this.

For example, a sandbox key looks like ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx and a production key looks like ypk_live_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Using the key

Include the key as a Bearer token on every request:

curl https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Node.js

await fetch("https://api.yuvexpay.com/v1/payments", {
  headers: {
    "Authorization": `Bearer ${process.env.YUVEX_API_KEY}`,
  },
});

Python

import os, requests

requests.get(
    "https://api.yuvexpay.com/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['YUVEX_API_KEY']}"},
)

Scopes

Each API key carries an explicit list of scopes. A request that calls an endpoint outside the key’s scopes is rejected with 403 FORBIDDEN.

Scope	What it allows
`payments:write`	Create payments and refunds
`payments:read`	List and fetch payments
`payments:refund`	Issue refunds on an existing payment
`withdrawals:write`	Create withdrawals
`withdrawals:read`	List and fetch withdrawals
`customers:write`	Create and update customers
`customers:read`	List and fetch customers
`products:write`	Create and update products
`products:read`	List and fetch products
`documents:read`	Read statements and documents
`webhooks:read`	List webhook deliveries
`balance:read`	Read the company’s account balance

The wildcard * scope grants access to every endpoint and is reserved for trusted server-to-server integrations. Choose the smallest set of scopes the integration needs. A public-website key that only creates PIX charges only needs payments:write.

Environments

The same base URL (https://api.yuvexpay.com) serves both environments — the key prefix decides which bucket the request lands in:

ypk_test_... → Sandbox. Fake money, predictable provider behaviour, webhooks fire, no financial impact.
ypk_live_... → Production. Real provider, real settlement, real money.

Use a ypk_test_ key during development. Switch the environment variable to a ypk_live_ key on deploy — the code path stays identical.

IP allowlist and rotation

Keys support an optional IP/CIDR allowlist (set it per key in the dashboard). When set, requests from outside the allowlist are rejected with 403 IP_NOT_ALLOWED even if the key is otherwise valid. Rotate keys by creating a new one, updating the integration, then revoking the old one. Key creation, rotation and revocation are auditable in the dashboard.

Inspecting the current key

Call GET /v1/auth/self to retrieve metadata about the key being used. The response is useful for verifying scopes, environment, IP allowlist and expiration without storing them client-side:

curl https://api.yuvexpay.com/v1/auth/self \
  -H "Authorization: Bearer $YUVEX_API_KEY"

{
  "apiKey": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "name": "Backend integration",
    "description": null,
    "environment": "PRODUCTION",
    "prefix": "ypk_live_ab12cd34ef",
    "scopes": ["payments:write", "payments:read", "withdrawals:write", "withdrawals:read"],
    "ipAllowlist": ["203.0.113.10"],
    "rateLimitPerMinute": 600,
    "expiresAt": null,
    "lastUsedAt": "2026-05-03T14:21:08.443Z",
    "createdAt": "2026-04-12T09:00:00.000Z"
  }
}

Getting started

Core concepts

Products

Creating an API key

Key format

Using the key

Scopes

Environments

IP allowlist and rotation

Inspecting the current key

​Creating an API key

​Key format

​Using the key

​Scopes

​Environments

​IP allowlist and rotation

​Inspecting the current key

Creating an API key

Key format

Using the key

Scopes

Environments

IP allowlist and rotation

Inspecting the current key