API Reference

Get session by reference

Look up a payment session using your merchantReference.

Request

GET/api/v1/payment-sessions?merchantReference={ref}

Look up a payment session using the merchantReference you supplied at create time. Returns the same merchant-safe object as GET by sessionId.

Headers and query

Name	Type	Required	Description
`X-Api-Key`	header	Required	Business API key (zp_live_…).
`X-Correlation-Id`	header	Optional	Optional trace identifier.
`merchantReference`	query	Required	Your order reference from create. Max 200 characters; trimmed; no control characters.

Response

200 response excerpt

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

See Get a payment session for the full field list, status values, and excluded fields.

Use cases

Reconcile an order when a webhook was missed or delayed.
Support lookup when you only have your internal order id.
Poll from your backend until status reaches a terminal state.

Errors

Name	Type	Description
`401`	Unauthorized	Invalid or missing API key.
`404`	Not Found	payment-session.not-found — no session for this reference on your business.
`422`	Unprocessable	Missing or invalid merchantReference query param.
`429`	Too Many Requests	120/min per API key. Retry after Retry-After.

Get Session by Reference

curl "https://api.zippypay.io/api/v1/payment-sessions?merchantReference=order-12345" \
  -H "X-Api-Key: zp_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123"

Get Session by Reference 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"
  }
}

Get a payment session

Webhooks overview