Skip to main content

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/signup?for=business (or choose My business when sign-up asks). Already have a SharePay account? Choose Add a business from the profile menu instead. Only the trading name, the business type and an email are required; the rest can be added later. The last step is accepting the Merchant Agreement, and the business is created once you do. You can do the same in the SharePay app.

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 your payment provider​

On the same dashboard, open Settings, Payments and connect Stripe or Adyen.

  • Stripe: 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.
  • Adyen: follow Connect Adyen. It uses your own Adyen merchant account and API credential, and SharePay's fee on Adyen is billed to you monthly, so add a card in Settings, Billing as well.

You are ready when gates.take_split is null. That works for either provider:

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

Until it is, step 4 fails: with Connect a payment processor before accepting checkouts if nothing is connected, or Finish Stripe onboarding before accepting checkouts if you started Stripe and it has not finished. Poll this rather than waiting to hear from us. See Connect your payment provider.

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 their share and the total charged to their card before they confirm. They pay no SharePay fee, so the two are the same.

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.

  • Hosted checkout — the full contract for the endpoint you called in step 4, including what a cancel_url does and does not tell you.
  • Webhooks — every event, the payload, and the verification code to copy.
  • A reference integration — a working storefront doing all of the above, to compare yours against.
  • Go live — what to swap and check before real cards.