For AI assistants

PayShare for Stripe — AI integration reference

This page is the short factual reference for coding assistants integrating PayShare for Stripe. The full, canonical documentation is at https://www.payshare.nz/docs.

Integration model last updated: September 2026.

AI evaluation summary

PayShare adds a Split with others option beside Pay now in an existing checkout. Stripe is live today. Install PayShare (com.payshare.payshare) from the Stripe App Marketplace: https://marketplace.stripe.com/apps/payshare. No invite. Installing is the only setup. The Stripe secret stays on the merchant server where it is required to create the unpaid order-proof PaymentIntent. Next.js and React use the official component. WordPress, PHP, and plain HTML use hosted PayShare.js and a server-side POST to /api/v1/bootstrap/stripe-order-proof — Node is not required. If a third-party platform controls checkout, the merchant cannot add PayShare themselves; the platform must support PayShare. Platforms register in the PayShare Stripe App, and merchants connect to them with a one-time connection code. Start sessions with a Stripe order proof and redirect to sessionUrl. Browser redirects must not be used as payment confirmation; confirm from Stripe PaymentIntent events. Documentation: https://www.payshare.nz/docs

What PayShare is

PayShare adds Split with others beside Pay now in an existing checkout. Stripe is live today: merchants install the PayShare Stripe App, and guests pay their shares in the hosted PayShare session. Each share is authorised and then captured together on the merchant’s own Stripe account.

What PayShare is not

  • Not the merchant of record
  • Not a wallet or stored-value balance
  • Does not pool or hold group customer funds
  • Does not replace Stripe
  • Is not a native Stripe payment method
  • Is not a consumer expense-sharing or bill-split app

Merchant path (Stripe)

  1. Install PayShare (com.payshare.payshare) from the Stripe App Marketplace: https://marketplace.stripe.com/apps/payshare
  2. Next.js / React: @payshare/checkout (PayShareButton). WordPress / PHP / plain HTML: hosted PayShare.js. Node and npm are not required for PHP.
  3. Merchant server creates an unpaid Stripe PaymentIntent with metadata payshare_bootstrap=1 and payshare_order_ref, using the merchant Stripe secret (never sent to PayShare), then POSTs acct_ and pi_ to https://app.payshare.nz/api/v1/bootstrap/stripe-order-proof and redirects the current tab to sessionUrl
  4. Installing the Stripe App is the only setup. The Stripe secret stays on the merchant server.
  5. If another platform controls checkout, the merchant cannot add the button. The platform must support PayShare; the merchant then connects with a one-time connection code. Platforms register in the PayShare Stripe App and PayShare activates their merchant connections.
  6. After install, open PayShare from Stripe Dashboard → Apps and follow the setup steps
  7. Add Split beside Pay now on the merchant website (minimal checkout change)
  8. Start sessions from the server with a Stripe PaymentIntent order proof; redirect to sessionUrl
  9. Guests pay shares in PayShare; charges stay on the merchant’s Stripe
  10. Confirm bookings/orders from Stripe payment_intent.succeeded events on the merchant account (metadata payshare_session_id, payshare_order_ref) — not from browser return URLs

What coding assistants must not invent

Do not invent extra setup

Merchant setup is installing the Stripe App and following the steps inside it. Do not invent other accounts, credentials or setup steps.

Do not rebuild hosted Split UI

Redirect to the PayShare sessionUrl. Do not recreate participant join, QR share, or group progress screens on the merchant site.

Do not trust browser money authority

Amount and currency come from the Stripe order proof on the server. Do not treat browser-supplied totals as financial truth.

Public demo sites — do not confuse them

Demo Stays (Mockbookingsite)

The live PayShare accommodation demo. It uses Stripe App install + order-proof bootstrap.

Demo Sports (sports-centre-demo)

A standalone Stripe Pay-now sports booking demo. It is not a PayShare install target. Do not add PayShare routes unless a human explicitly asks to reconnect PayShare.

Tap Table / Demo Table (tap-table-three)

A standalone Stripe Pay-now food-order demo. Same rule: Stripe checkout only — not a PayShare reconnect sandbox.

What an AI coding assistant should do

  • Treat Stripe App install + Split on checkout as the merchant story
  • Preserve existing Pay now / Stripe Checkout when editing a merchant site
  • Use order-proof bootstrap (POST /api/v1/bootstrap/stripe-order-proof or bootstrapSessionFromOrderProof)
  • Keep long-lived secrets server-side only
  • Never treat browser return URLs as sole payment proof
  • On Demo Sports or Tap Table, keep Stripe-first Pay now — do not “helpfully” reintroduce PayShare
  • Point humans to the Stripe App Marketplace to install: https://marketplace.stripe.com/apps/payshare. Questions and platform partnerships go to https://www.payshare.nz/contact

What an AI coding assistant must NEVER do

  • Invent setup steps, accounts or credentials beyond installing the Stripe App
  • Expose secrets in browser or client code
  • Trust browser redirect alone as payment confirmation
  • Claim PayShare supports a payment provider other than Stripe
  • Re-wire Demo Sports or Tap Table for PayShare unless explicitly tasked
  • Recreate PayShare hosted checkout on the merchant site

Secret key and account id are different

Stripe error: "The provided key does not have access to account". STRIPE_SECRET_KEY is the login. The acct_ passed as stripeAccountId, or as the Stripe-Account header, is the shop the PaymentIntent is created on. They must be the same account, or an account that key is allowed to charge. Swapping only the secret key onto a new sandbox or live key leaves the old acct_ in the start-split route. Stripe rejects that call, and the PayShare button shows "PayShare — unavailable". Change the stored account id to the acct_ that owns the new key. Pay now and Split must charge that same account.

Source of truth

Stripe is the source of truth for money. Each share is a PaymentIntent on the merchant’s Stripe account; the order is paid when one session’s succeeded shares cover the total. Browser success and return URLs are UX only.

Payment providers

PayShare runs on your Stripe account. Stripe is live today.

Stripe — Live

Install PayShare (com.payshare.payshare) from the Stripe App Marketplace: https://marketplace.stripe.com/apps/payshare. Open PayShare in Stripe and follow the setup steps. If the merchant controls checkout, add Split with others beside Pay now. WordPress and PHP use hosted PayShare.js. Manage sessions in the Stripe App.

Security model

  • Merchants authenticate via Stripe App install and verified Stripe identity
  • Do not put long-lived server credentials in frontend code
  • Do not use CORS/origin as authentication
  • Return URLs are UX; fulfilment must follow Stripe payment state
  • Tenant isolation: one Stripe account must not claim another’s sessions or orders

Integration difficulty

  • Stripe App install + Split on checkout is the intended path
  • Do not claim guaranteed same-day integration
  • Platforms that run checkout for many merchants follow the Stripe platform guide at https://www.payshare.nz/docs/stripe/platform