Authentication and API keys

The API uses bearer authentication. Send the key in the Authorization header of every request:

curl https://pay.example.com/v1/payment_intents?limit=3 \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

A missing, malformed, revoked or unsuitable key returns 401 with error.type = authentication_error. Always use HTTPS for live installations.

Key types

Create, list and revoke keys under Developers → API keys in the merchant panel (or with /v1/api_keys from a panel session). The secret is displayed only once at creation. Revoking a key takes effect immediately; roll a key by creating a new one, deploying it, then revoking the old one.

Scopes of restricted keys

A restricted key carries scopes of the form <resource>:read or <resource>:write; write includes read. A call outside the key's scopes returns 403 with error.type = permission_error.

Resources: payment_intents, installment_plans, refunds, disputes, balance, balance_transactions, topups, payouts, settlement_accounts, webhook_endpoints, events, customers, payment_methods, request_logs, reporting, products.

For example, a refund service needs refunds:write and payment_intents:read; a reconciliation job needs balance_transactions:read and payouts:read.

API version

Your account is pinned to an API version. Override it per request with the header PF-Version: YYYY-MM-DD; the version used is echoed in the response PF-Version header.

IP allowlist

Secret and restricted keys can be limited to the server IP addresses you register. Publishable keys and panel sessions are not subject to the list.

1. Open Settings → Allowed IP addresses in the merchant panel.
2. Add a single IPv4 or IPv6 address, or a CIDR block (IPv4 no wider than /8, IPv6 no wider than /16). An entry may be tied to one API key; a key that has its own entries is admitted only from those, every other key from the account-wide entries.
3. New entries are pending until the payment institution approves them. Removing an entry takes effect immediately.

A request from an address that is not allowed is refused with 403 ip_not_allowed. In sandbox installations a violation is only recorded as a warning in Developers → Logs; in live installations it is refused. When no address is registered and the list is enforced, every server request is refused, so register your addresses before going live.

If your servers sit behind a proxy or NAT, register the public egress address, not the internal one.

Callback URL and website registration

Payment institutions must know where you take payments and where customers and notifications are sent. Register these under Settings → Websites & callbacks:

• Websites you take payments on (domain names, https in live). Verification is by DNS TXT record or manual review.
• Callback URLs you use as 3-D Secure return_url and as webhook endpoint URLs. A URL matches either exact (scheme, host, port and path) or by prefix at a path-segment boundary (/pay matches /pay and /pay/done, not /payment).

A return_url or a webhook URL that is on an approved website or matches a registered callback URL is accepted; otherwise the call fails with 400 return_url_not_allowed (param: return_url) or 400 webhook_url_not_allowed (param: url), and a payment from an unregistered website fails with 403 website_not_registered. As with IP addresses, additions wait for approval, removals apply immediately, and sandbox installations warn where live installations refuse.

Plan for the approval time: register your production domain, return URL and server IP addresses well before launch.

Errors you may see here

The complete list is in the errors guide.