Authenticate with a Payclave API key
Send a key with Authorization: Bearer or the X-API-Key header. Secret keys use sk_test_ or sk_live_ prefixes and belong on your backend. Publishable keys use pk_test_ or pk_live_ prefixes and are intended for limited browser checkout integration. Create and manage your keys in the authenticated merchant dashboard; never put a secret key into a browser bundle.
curl https://api.payclave.com/v1/checkout-sessions \
-H 'Authorization: Bearer sk_test_REPLACE_ON_YOUR_SERVER' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order_8431' \
-d '{"amount":"25.00","externalReference":"order_8431"}'Use the right key and mode
Publishable keys can create and read checkout sessions. Publishable-key creation accepts only amount and externalReference. Use a secret key for invoice and payment APIs, webhook management, and trusted checkout fields such as customer email and return URLs. The key selects test or live mode and the merchant settlement configuration; switching a request field does not switch modes.
The recommended production flow is for your backend to calculate the trusted amount, create the checkout session with a secret key, and send the resulting Payclave checkout URL to your frontend. An Idempotency-Key can protect supported retries, but it is not an authentication credential. Webhook signature verification is a separate step using the signing secret and the exact raw request body.
Handle authentication failures
An unauthenticated request returns HTTP 401 with the Payclave error envelope, including a machine-readable error.code and meta.requestId. Correct the missing or invalid credential before retrying. An authenticated key can still lack permission for an operation; use the API's error code and HTTP status to distinguish these failures.