API Reference

Create a payment session

Create an amount-locked checkout session and receive a client token.

Request

POST/api/v1/payment-sessions

Creates an amount-locked checkout session and returns a one-time client token for @zippypay/checkout. Send the request from trusted backend infrastructure with your API key.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Required	Business API key with a zp_live_ prefix and 32-character Base64URL secret.
`Content-Type`	string	Required	application/json
`Idempotency-Key`	string	Optional	Optional non-empty string. A UUID v4 is strongly recommended.
`X-Correlation-Id`	string	Optional	Optional trace identifier. Zippy generates a UUID when omitted.

JSON body

Name	Type	Required	Description
`amount`	decimal string	Required	USD amount locked for the session lifetime, e.g. "25.00".
`currency`	string	Optional	Optional. "USD" only (default).
`merchantReference`	string	Optional	Optional merchant order reference. Max 200 characters. Unique per business.
`successUrl`	url	Optional	Optional HTTPS redirect after successful checkout. Origin must match a registered allowed checkout domain or your registered business website.
`failureUrl`	url	Optional	Optional HTTPS redirect after failure or expiry. Same origin rules as successUrl.
`metadata`	object	Optional	Optional non-sensitive JSON object. Max 4096 UTF-8 bytes. No arrays.

Field validation

Amount and currency

amount must be a positive USD decimal string with up to two fractional digits (for example 25.00 or 0.50). The amount is locked when the session is created and is not echoed in the create response — the Checkout SDK reads the locked value returned to the Checkout SDK when checkout loads.

currency accepts USD only. Omit it to use the default.

Merchant reference

merchantReference is optional (max 200 characters). When supplied, it must be unique among active sessions for your business. Reusing a reference for a different payload returns 409 payment-session.reference-conflict.

Redirect URLs

When successUrl or failureUrl are sent:

Must use HTTPS (credentials in URLs are not allowed).
The URL origin must match a registered allowed checkout domain under Integrations → Allowed browser origins, or your registered business website.
If redirect URLs are sent but no permitted origins exist, create fails.

Valid redirect URLs (checkout.acme.com registered)

json

{
  "successUrl": "https://checkout.acme.com/order/123/success",
  "failureUrl": "https://checkout.acme.com/order/123/cancel"
}

Invalid or unregistered origins return 400 payment-session.redirect-url-invalid.

Metadata

metadata must be a JSON object with string keys and scalar values only — no arrays. Keep values non-sensitive. Exceeding 4096 UTF-8 bytes returns 400 payment-session.metadata-too-large.

Idempotency

Generate one UUID v4 for each logical create operation and reuse it only when retrying the same request. The server accepts any non-empty string, but UUID v4 is strongly recommended.

Recommended header

http

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

Same tenant, route, key, and payload: returns the existing session.
Same key with a different payload: 409 IDEMPOTENCY_CONFLICT.
Reuse after the associated session becomes terminal: 409 IDEMPOTENCY_CONFLICT.

Response

201 response excerpt

json

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "clientToken": "zps_REDACTED",
  "expiresAt": "2026-08-31T12:30:00.000Z"
}

Errors

Name	Type	Description
`400`	Bad Request	Validation failure, unknown property, redirect URL invalid, or metadata too large.
`401`	Unauthorized	Missing, invalid, expired, or revoked API key (api-key.invalid, api-key.revoked, api-key.expired).
`403`	Forbidden	business.compliance-not-approved, business.not-active, or business.payment-id-not-configured.
`409`	Conflict	Idempotency key reused incompatibly or merchantReference conflict.
`429`	Too Many Requests	Rate limit exceeded (120/min per API key). Retry after Retry-After.

Create Payment Session

curl -X POST "https://api.zippypay.io/api/v1/payment-sessions" \
  -H "X-Api-Key: zp_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 83596f5e-2134-4e66-8304-20d61f290cf0" \
  --data '{
  "amount": "25.00",
  "currency": "USD",
  "merchantReference": "order-12345"
}'

Create Payment Session Response

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "clientToken": "zps_REDACTED",
  "expiresAt": "2026-08-31T12:30:00.000Z"
}

Overview

Get a payment session