API Reference

Base URL: https://app.payshare.nz

Auth: All session-creation and merchant endpoints require header X-PayShare-API-Key: ps_... (server-to-server only; never call from the browser).

Create session (canonical)

POST /api/v1/payments/sessions

Headers: Content-Type: application/json, X-PayShare-API-Key: ps_...

Request body:

Field	Type	Required	Description
`integrationId`	string (UUID)	Yes	Your integration ID from Admin
`amount`	number	Yes	Total amount to split (> 0)
`currency`	string	No	Default `NZD`
`unconfigured`	boolean	No	Default `true` — host configures participants and split on first visit
`successUrl`	string	No	Redirect when session completes (allowlisted)
`cancelUrl`	string	No	Redirect when user cancels
`metadata`	object	No	Custom data (e.g. merchantOrderRef)
`merchantOrderRef`	string	No	Your order/booking reference; echoed in webhook as orderReference

Success (200):

{
  "success": true,
  "sessionId": "uuid",
  "hostToken": "opaque-token",
  "participantIds": [],
  "mode": "live",
  "message": "Unconfigured session created - host must configure before inviting participants"
}

Redirect URL: Build the pay URL as: https://app.payshare.nz/pay/{sessionId}?host=1&hostToken={hostToken}. Redirect the host to this URL.

Use sessionId and hostToken only for server-side redirects; never log them or expose in client-side analytics.

Errors: See Error codes. Typical: INVALID_AMOUNT, MISSING_API_KEY, INVALID_API_KEY, INTEGRATION_DISABLED, RATE_LIMIT_EXCEEDED (429).

Legacy alias: POST /api/payments/sessions is supported; prefer /api/v1/... for new integrations.