Quickstart

Take one split end to end on the sandbox, with a Stripe test card, before you write any real integration code. Nothing here charges a real card and nothing here touches your live account.

Everything below happens on demo.share-pay.co.uk. It is a separate backend with its own database, its own Stripe keys and its own merchant accounts, so your live credentials do not work against it and nothing you do here reaches production. See Testing.

1. Register your business

Sign up at demo.share-pay.co.uk, then choose Add a business from the profile menu. Only the trading name, the business type and an email are required; the rest can be added later.

Then create an API key (sp_prod_..., or sp_test_... in test mode) under Settings, Developers. It is shown once, so copy it into your server's environment straight away. Create a webhook secret on the same page when you set up your endpoint.

The API key is what your server uses to start a checkout. It authenticates nothing else. See Two credentials, two different scopes.

2. Connect Stripe

On the same dashboard, start Stripe Connect onboarding and complete Stripe's hosted flow. On the sandbox it runs in Stripe test mode, so it verifies nothing real and you can put in placeholder details.

You are ready when stripe_charges_enabled is true:

curl https://demo.share-pay.co.uk/api/merchants/me \
  -H "Authorization: Bearer <your dashboard session token>"

Until that flag flips, step 4 fails with Finish Stripe onboarding before accepting checkouts. Poll this rather than waiting to hear from us — see Connect Stripe.

3. Set your allowed return domain

Open Developers, then Allowed return domain, and enter the bare hostname your shop runs on, for example your-shop.example.

Step 4 rejects every return_url until this is set. The check is an exact, case-insensitive hostname match, and it does not cover subdomains: an allowed domain of your-shop.example will not accept https://shop.your-shop.example/.... See Set your allowed return domain first.

While you are on that page, set your webhook endpoint URL too. It must be a public https:// address, so a localhost tunnel hostname is rejected on save.

4. Create a checkout session

From your server, never from a web page. The API key must never reach a browser — and it would not work there anyway, because browsers are not allowed to send that header to our API.

curl -X POST https://demo.share-pay.co.uk/api/merchants/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "x-merchant-api-key: sp_prod_..." \
  -d '{
    "amount": 120.00,
    "order_reference": "TEST-001",
    "return_url": "https://your-shop.example/order/complete",
    "cancel_url": "https://your-shop.example/basket"
  }'

amount is in pounds, between £1 and £5000. "amount": 12000 means £12,000 and is rejected.

You get back { token, checkout_url }. Save the token against your order now: it is the only handle your server keeps on this order, and the only split-state surface an API key can reach.

5. Pay as the buyer

Open checkout_url in a browser. You are the buyer here: sign in, invite one or two participants and give each of them an amount. The shares must add up exactly to the amount you sent, and no share may be under £1.

Each participant opens their own link and authorises with a test card:

4242 4242 4242 4242
Any future expiry date, any CVC

Each of them sees three lines before they confirm — their share, a flat 20p SharePay service fee, and the total charged to their card.

Nothing is captured until the last participant approves. Until then every share is an uncaptured hold and no money has moved.

6. Receive the webhook

When the last person approves, all the holds capture together and SharePay posts checkout_split.paid to your endpoint.

That event is what you fulfil the order on — not the buyer landing back on your return_url, which only means the split was set up.

Before you trust it, check the X-SharePay-Signature header proves the request really came from us. It is a signature made with your webhook secret, and verifying it is a few lines of code. See Verify the signature.

Failed deliveries are not retried automatically. Resend them from the delivery log on the Developers page, and reconcile anything that never arrives by polling the session token from step 4. See Reconciling without a webhook.

1. Register your business​

2. Connect Stripe​

3. Set your allowed return domain​

4. Create a checkout session​

5. Pay as the buyer​

6. Receive the webhook​

What to read next​