Quickstart

Prerequisites: PayShare integration (Admin), Integration ID, API key (ps_...), and (for completion) signing secret.

1. Create a session (backend, server-to-server only)

curl -X POST https://app.payshare.nz/api/v1/payments/sessions \
  -H "Content-Type: application/json" \
  -H "X-PayShare-API-Key: ps_YOUR_API_KEY" \
  -d '{
    "integrationId": "YOUR_INTEGRATION_ID",
    "amount": 50.00,
    "currency": "NZD",
    "unconfigured": true,
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/checkout"
  }'

Response:

{ "success": true, "sessionId": "...", "hostToken": "...", "participantIds": [], "mode": "live" }

Store sessionId and hostToken; use them only server-side or in redirect URLs, never in client logs.

2. Send the host to PayShare

Redirect the host to:

https://app.payshare.nz/pay/{sessionId}?host=1&hostToken={hostToken}

The host chooses number of participants and split, then shares the single link/QR from the hub.

3. Completion

When everyone has paid, PayShare sends a webhook (POST to your Webhook URL) with a signed payload. Use the webhook as the only source of truth for marking the order paid and sending confirmations. Verify the X-PayShare-Signature header using your signing secret and use eventId for idempotency.

PayShare also redirects the user to your successUrl with signed query params—use that only to show a thank-you or confirmation page, not to decide that payment succeeded. If the user never loads the success page (e.g. closed tab), the webhook still fires and your backend can mark the order paid.

Optional: SDK for "open in modal/new tab"

Load the SDK, then open a session (amount from your checkout):

<script src="https://app.payshare.nz/api/integration-sdk?id=YOUR_INTEGRATION_ID&v=v1.0.0"></script>
<script>
  PayShare.init({ integrationId: 'YOUR_INTEGRATION_ID' });
  PayShare.open({ amount: 50.00, currency: 'NZD' });
</script>

Use the API for session creation and redirect for the hosted flow; use the SDK when you want a button that opens PayShare with a known amount.

Next: API Reference · Webhooks · Error codes