Start

Authentication

Separate credentials for your server, checkout SDK, and webhooks.

Zippy Pay uses four distinct credential types. Each is scoped to a specific surface — never mix them across server, browser, and webhook handlers.

Credential overview

Four credentials, four surfaces

Name	Type	Description
`Business API key`	zp_live_…	Server-only. Create sessions, poll status, and reconcile by sessionId or merchantReference.
`Client token`	zps_…	Browser-safe. Returned when creating a session; passed to @zippypay/checkout.
`Webhook signing secret`	whsec_…	Server-only. Verifies X-Zippy-Signature on inbound webhook POSTs.
`Session identifier`	UUID	Public session reference (sessionId). Safe to pass to the SDK with the client token.

Business API key

Keys contain the zp_live_ prefix followed by a secret value. The plaintext key is shown once when created in the portal. Send it only from trusted backend infrastructure.

Header

http

X-Api-Key: zp_live_REDACTED

Merchant key errors

Name	Type	Description
`api-key.invalid`	401	Missing, malformed, or unmatched key.
`api-key.revoked`	401	Key revoked in the portal.
`api-key.expired`	401	Key expiry date is in the past.

Payment session token

When you create a payment session, the response includes a clientToken prefixed with zps_. Pass it to the Checkout SDK together with sessionId. It authorizes checkout for that session only and expires with the session.

Client token (example)

text

zps_REDACTED

Webhook signing secret

When you register a webhook endpoint, Zippy shows a signing secret once, prefixed with whsec_. Use it to verify X-Zippy-Signature over the exact raw request body.

Webhook secret (example)

text

whsec_example_secret_for_documentation_only

See Verify webhook signatures for language examples and the verification playground.

Correlation IDs

Send an optional X-Correlation-Id on create session requests to connect your logs with Zippy request logs. If omitted, Zippy generates a UUID. The effective correlation ID is returned in the response header and included in Problem Details responses.

Optional request header

http

X-Correlation-Id: merchant-request-123

Idempotency

Send Idempotency-Key on every POST /api/v1/payment-sessions request. Use one UUID v4 per logical checkout attempt and keep it unchanged when retrying the same payload.

Idempotency header

http

Idempotency-Key: 83596f5e-2134-4e66-8304-20d61f290cf0

Problem Details

Errors use application/problem+json. Branch on the stable code field and retain correlationId when contacting support.

Problem Details response

json

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is missing or invalid",
  "instance": "/api/v1/payment-sessions",
  "code": "api-key.invalid",
  "correlationId": "c7ccb49d-e6bb-45f7-b834-93c4521a6857"
}

Security practices

Store zp_live_ and whsec_ values in a secrets manager or encrypted environment configuration.
Send merchant-server requests only over HTTPS.
Pass only sessionId and zps_ client tokens to browser code.
Use a separate API key per environment and revoke keys that may be compromised.

Common failures

Sending zp_live_ from the Checkout SDK or a mobile app.
Using zps_ as X-Api-Key on merchant-server routes.
Verifying webhooks with the API key instead of whsec_.
Omitting Idempotency-Key and creating duplicate sessions on network retries.

Getting started

Core concepts