Authentication

All server-side requests to Paymnt Cloud use API keys. Send your secret key in the api-key header. If you use routing profiles, include x-profile-id.

Production: https://api.paymnt.cloud
Sandbox: https://sandbox.paymnt.cloud

Never expose secret keys in browsers or mobile apps. Keep keys in your server environment variables or your secret manager.

Headers

api-key: <YOUR_SECRET_KEY>
x-profile-id: <pro_...>   # optional, only if profiles are enabled
Idempotency-Key: <uuid-v4>   # recommended for POST/PUT/PATCH

api-key — required for all authenticated calls
x-profile-id — lets you target a specific routing/profile configuration
Idempotency-Key — prevents duplicate processing on retries for mutating requests

Key scope & environments

Keys are environment-scoped. Create separate keys for Sandbox and Production
Rotate keys periodically; remove old keys from all deployments
Limit who can view/rotate keys via RBAC. See RBAC & Keys
For local dev and CI/CD, load keys via environment variables. See Environments

Using the API Reference (Try it)

In the API reference tab, open any endpoint and use Try it. Enter your api-key (and x-profile-id if used) once; it will be applied to subsequent requests. If your OpenAPI lists both servers, you can switch between Sandbox and Production from the server selector. Browser-based calls originate from your docs domain (e.g., https://docs.paymnt.cloud). Ensure CORS allows that origin only if you plan to call your API from the docs.

Examples

cURL — list customers

curl -X GET "https://api.paymnt.cloud/customers" \
  -H "Accept: application/json" \
  -H "api-key: <YOUR_SECRET_KEY>" \
  -H "x-profile-id: <pro_...>"    # optional

cURL — create payment (with idempotency)

curl -X POST "https://api.paymnt.cloud/payments" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_SECRET_KEY>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000001" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "description": "Order #1001"
  }'

Node (fetch)

const base = process.env.PAYMNT_BASE_URL || "https://sandbox.paymnt.cloud";

const res = await fetch(`${base}/customers`, {
  headers: {
    "Accept": "application/json",
    "api-key": process.env.PAYMNT_API_KEY,
    ...(process.env.PAYMNT_PROFILE_ID ? { "x-profile-id": process.env.PAYMNT_PROFILE_ID } : {})
  }
});

const customers = await res.json();
console.log(customers);

Python (requests)

import os, requests

base = os.getenv("PAYMNT_BASE_URL", "https://sandbox.paymnt.cloud")
headers = {
    "Accept": "application/json",
    "api-key": os.getenv("PAYMNT_API_KEY"),
}
profile_id = os.getenv("PAYMNT_PROFILE_ID")
if profile_id:
    headers["x-profile-id"] = profile_id

r = requests.get(f"{base}/customers", headers=headers, timeout=30)
print(r.status_code, r.json())

Errors

401 Unauthorized — missing/invalid api-key
403 Forbidden — the key is valid but not permitted for the action/profile

Log the request_id from error bodies for support and correlation. See Error Codes.

Good practices

Keep keys server-only; never hardcode them in client apps
Use idempotency for all mutating requests; implement retry with jitter for transient failures
Store keys in a secret manager; rotate on a schedule; monitor usage
Separate Sandbox vs Production keys and configs; do not reuse across environments. See Environments

Getting Started

Essentials

Guides — Payments

Guides — Customers

Guides — Refunds

Guides — Disputes

Routing & Connectors

Webhooks & Events

SDKs & Tools

Sandbox & Testing

Security & Compliance

Operations

Support & FAQ

Headers

Key scope & environments

Using the API Reference (Try it)

Examples

cURL — list customers

cURL — create payment (with idempotency)

Node (fetch)

Python (requests)

Errors

Good practices

​Headers

​Key scope & environments

​Using the API Reference (Try it)

​Examples

​cURL — list customers

​cURL — create payment (with idempotency)

​Node (fetch)

​Python (requests)

​Errors

​Good practices

Headers

Key scope & environments

Using the API Reference (Try it)

Examples

cURL — list customers

cURL — create payment (with idempotency)

Node (fetch)

Python (requests)

Errors

Good practices