Integration reference (booking systems)
Helps developers integrate PayShare into booking or checkout systems. Describes PayShare's integration model on its own terms.
Booking and checkout systems need to handle three outcomes: success (paid), cancel (user cancelled), and expired (session timed out). PayShare provides webhooks and redirects for each.
Webhook = source of truth. Use the webhook to mark orders paid and trigger fulfilment. The success URL is for the thank-you page only. Do not rely on the redirect to decide payment succeeded.
PayShare integration terms
| Term | Description |
|---|---|
| successUrl | Where the user is sent after payment and clicking Done. For UX only; do not use to mark order paid. |
| cancelUrl | Where the user is sent if they cancel. |
| merchantOrderRef | Your order or booking reference; echoed in the webhook as orderReference. Use it to look up your order. |
| PAYSHARE_SESSION_COMPLETED | All participants have paid. Use this event to trigger fulfilment (mark order paid, send confirmation). |
| PAYSHARE_SESSION_CANCELLED | User or host cancelled. Update order state; do not trigger fulfilment. |
| PAYSHARE_SESSION_EXPIRED | Session timed out. Update order state; do not trigger fulfilment. |
| eventId | Unique event id. Use for idempotency—return 200 if you already processed this event. |
Outcome mapping
| Outcome | PayShare event | Your handler |
|---|---|---|
| Success (paid) | PAYSHARE_SESSION_COMPLETED | Mark order paid; send confirmation |
| Cancel | PAYSHARE_SESSION_CANCELLED + redirect to cancelUrl | Keep pending or mark cancelled |
| Expired | PAYSHARE_SESSION_EXPIRED | Release inventory; mark abandoned |
Handler pattern
Your backend needs three logical handlers: onSuccess, onCancel, onExpired. When you receive a webhook, route by eventType and invoke the appropriate handler. Look up your order by orderReference or sessionId (you stored sessionId when creating the session).
See: Webhooks · Quickstart