Skip to main content
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
See also: Profiles • Idempotency

​
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