API Reference

Get a payment session

Read merchant-safe session status by sessionId with your API key.

Request

GET/api/v1/payment-sessions/{sessionId}

Returns a merchant-safe view of the payment session for reconciliation and server-side polling. Authenticate with X-Api-Key from your backend only — never from the browser.

Headers and path

Name	Type	Required	Description
`X-Api-Key`	header	Required	Business API key (zp_live_…). Returns the merchant-safe payload.
`X-Correlation-Id`	header	Optional	Optional trace identifier.
`sessionId`	uuid	Required	Payment session UUID v4 from create.

Path validation

sessionId must be UUID v4. Malformed values return 400 payment-session.id-invalid.

Sessions are scoped to the business tied to your API key. A valid UUID belonging to another business returns 404 payment-session.not-found (not 403).

Response

Merchant session object

Name	Type	Description
`sessionId`	uuid	Payment session identifier.
`status`	enum	Session lifecycle status (see below).
`amount`	decimal string	Locked payment amount.
`currency`	"USD"	Always USD today.
`merchantReference`	string \| null	Your order reference from create.
`metadata`	object	Opaque key/value from create (max 4096 UTF-8 bytes).
`transactionId`	uuid \| null	Zippy transaction id once a payer is linked. Use for receipts and support.
`transactionStatus`	enum \| null	Linked transaction status when available.
`payer`	object \| null	Attached payer (paymentId, displayName). Null until bound.

CreatedAwaiting PaymentCompletedExpiredCancelledFailed

200 — in progress

json

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

200 — completed

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"
  }
}

Alternatively, look up by your order reference: GET by merchantReference.

Excluded fields

Merchant reads intentionally exclude checkout internals and sensitive data:

Redirect URLs, business name, checkout phase/method, pay-window timestamps
Payer email, phone, user id, profile image
Gateway, vault, or billing provider identifiers

Errors

Name	Type	Description
`400`	Bad Request	payment-session.id-invalid — sessionId is not UUID v4.
`401`	Unauthorized	Invalid or missing API key.
`404`	Not Found	payment-session.not-found — unknown session or wrong business.
`429`	Too Many Requests	120/min per API key or client IP. Retry after Retry-After.

Get Payment Session

curl "https://api.zippypay.io/api/v1/payment-sessions/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: zp_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123"

Get Payment Session Response

{
  "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"
  }
}

Create a payment session

Get session by reference