Authentication & Keys

PerfectPay uses a simple header-based authentication pattern. Both server-side and client-side requests use the api-key header.

Dashboard Paths

• Developers -> API Keys: create and rotate secret keys, copy publishable keys
• Developers -> Settings: copy your hosted SDK details and environment configuration

Key Hosts

Secret API Key

Use your secret key for all server-to-server calls. Pass it in the api-key header:

api-key: YOUR_SECRET_API_KEY

Use this format for:

• POST /payments
• POST /payments/{payment_id}/confirm
• POST /payments/{payment_id}/capture
• POST /payments/{payment_id}/cancel
• POST /customers
• POST /refunds
• POST /payment_methods
• POST /subscriptions

Example

curl https://sandbox.perfectpay.ai/payments \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999, "currency": "USD"}'

Publishable Key

Use your publishable key for client-side calls. It uses the same api-key header:

api-key: YOUR_PUBLISHABLE_KEY

The publishable key is safe to include in browser code and mobile apps. It can only be used to retrieve payment status and interact with the Web SDK -- it cannot create payments or issue refunds.

The client secret is passed separately, either in the request body or as a query parameter, depending on the endpoint. It is not part of the auth header.

Required Values

Security Defaults

• Keep secret keys on your server only.
• Rotate keys when moving environments or changing backend ownership.
• Store keys in your secrets manager, not in application code or frontend bundles.
• Clear saved example credentials from this docs page when you finish debugging on a shared machine.