Skip to main content
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

  1. Log in to the YuvexPay dashboard.
  2. Open Settings > API Keys.
  3. Click Create key, choose the environment (sandbox or production) and pick the scopes the integration needs (see below).
  4. 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.
ScopeWhat it allows
payments:writeCreate payments and refunds
payments:readList and fetch payments
payments:refundIssue refunds on an existing payment
withdrawals:writeCreate withdrawals
withdrawals:readList and fetch withdrawals
customers:writeCreate and update customers
customers:readList and fetch customers
products:writeCreate and update products
products:readList and fetch products
documents:readRead statements and documents
webhooks:readList webhook deliveries
balance:readRead 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"
  }
}