Core concepts

Payment session

A payment session is the durable checkout object for a single payment attempt. Your backend creates it with a locked amount and currency; the Checkout SDK and Zippy mobile app operate on that session until it reaches a terminal status.

Create session response

json

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

Track sessions by sessionId (for example 550e8400-e29b-41d4-a716-446655440000) on your order or cart record. Session statuses include Created, Awaiting Payment, and Completed. See Session lifecycle for transitions and timers.

Merchant vs SDK responses

The same GET /payment-sessions/:sessionId path serves two audiences depending on the credential:

Name	Type	Description
`X-Api-Key`	merchant backend	Returns a merchant-safe reconciliation object: status, amount, merchantReference, transactionId, and limited payer fields. Excludes redirect URLs, checkout internals, and sensitive payer data.
`X-Payment-Session-Token`	Checkout SDK	Returns the full checkout view for the embedded UI (unchanged). Documented in the Checkout SDK guides, not the merchant API reference.

Merchant GET response (example)

json

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "amount": "25.00",
  "currency": "USD",
  "merchantReference": "order-12345",
  "metadata": { "orderId": "12345" },
  "transactionId": "880e8400-e29b-41d4-a716-446655440003",
  "transactionStatus": "COMPLETED",
  "payer": {
    "paymentId": "john.doe12",
    "displayName": "John Smith"
  }
}

Client token

The clientToken (zps_...) is a short-lived, session-scoped credential returned at creation time. Pass it to @zippypay/checkout with sessionId — it is safe for browser use unlike your zp_live_ API key.

Example client token

text

zps_REDACTED

Amount locking

The amount and currency you send at session creation are locked for the life of the session. Customers cannot change the payable total in checkout — if your cart changes, create a new session with a new idempotency key.

Name	Type	Description
`amount`	decimal string	Payable total, e.g. "25.00". Must match your order total at checkout time.
`currency`	ISO 4217	Three-letter code, e.g. "USD".

Redirect URLs

Provide successUrl and failureUrl when creating a session. After checkout completes or fails, the SDK can redirect the customer to these URLs for post-payment UX.

Both URLs must use HTTPS. The origin must match a registered allowed checkout domain (Integrations → Allowed browser origins) or your registered business website. Register each production domain where checkout and redirects run — including www and apex if both are used.

Name	Type	Description
`successUrl`	HTTPS URL	Customer lands here after a successful payment (when redirect is enabled). Origin must be on the allowlist.
`failureUrl`	HTTPS URL	Customer lands here after cancellation or payment failure. Same origin rules as successUrl.

Merchant reference

merchantReference is your stable order or cart identifier (for example order-12345). Zippy echoes it in webhook payloads and merchant GET responses so you can match events to internal records without relying on sessionId alone.

Name	Type	Description
`merchantReference`	string	Your order ID, invoice number, or cart key. Returned on session and webhook payloads.

Metadata

Attach optional metadata key-value pairs at session creation for internal correlation. Metadata is not shown to payers in checkout but is available on webhook events for your handlers.

Metadata example

json

{
  "metadata": {
    "orderId": "12345",
    "storeId": "nyc-001"
  }
}

Keep metadata small and non-sensitive. Do not store PANs, government IDs, or other regulated data in metadata fields.