Quickstart

Create a split session, wire create-payment, and handle completion via webhook.

Prerequisites: Integration ID, API key (ps_…), webhook signing secret, and partner create-payment signing secret from the Partner dashboard.

1. Create a session (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",
    "amountMinor": "50000",
    "currency": "NZD",
    "unconfigured": true,
    "merchantOrderRef": "BOOKING-123",
    "successReturnUrl": "https://yoursite.com/booking/complete?booking_id=BOOKING-123"
  }'

Store sessionId and hostToken server-side. Redirect the host to the sessionUrl from the response (or build /session/{id}?host=1&hostToken=… on app.payshare.nz).

2. Configure partner create-payment

On the integration, set partnerCreatePaymentUrl (e.g. https://yoursite.com/api/payshare/create-payment) and partnerCreatePaymentSigningSecret. When a payer taps Pay, PayShare POSTs a signed payload; return { "redirectUrl": "https://checkout.stripe.com/..." }.

3. Stripe success bridge

Point Stripe success_url at your GET route (e.g. /api/payshare/stripe-success). Retrieve the Checkout Session, POST record-payment (authorize), then 302 to payshareHostResumeUrl (host) or payshareParticipantReturnUrl (guest). Never return JSON { ok: true } to the browser.

4. Completion

Verify PAYSHARE_SESSION_COMPLETED on your webhook URL. Mark the booking paid once per eventId. Use successReturnUrl only for the thank-you / confirmation page.