Skip to main content

Hosted checkout

For taking splits from your own checkout, rather than the SharePay dashboard.

1. Create a checkout session​

Send your API key as x-merchant-api-key on:

POST /api/merchants/checkout/sessions

Call this 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.

{
"amount": 120.00,
"order_reference": "ORDER-123",
"return_url": "https://your-shop.example/order/complete",
"cancel_url": "https://your-shop.example/basket",
"customer_email": "[email protected]",
"customer_name": "Alex Morgan",
"metadata": { "order_id": "1042", "channel": "web" },
"line_items": [
{ "description": "Aeroflow helmet, matte black", "quantity": 1, "amount": 108.00,
"image_url": "https://cdn.your-shop.example/helmet.jpg" },
{ "description": "Rear light", "quantity": 2, "amount": 8.00 },
{ "description": "Delivery", "amount": 4.00 }
]
}

Returns 201 with { token, checkout_url }. The session is valid for 2 hours.

FieldRequiredNotes
amountYesPounds, not pence. Must be between 1 and 5000 inclusive. Decimals are fine, so £120.50 is 120.50.
order_referenceNoYour own reference, shown to the buyer. Defaults to Order.
return_urlYesWhere the buyer is sent once the split is set up.
cancel_urlNoWhere a buyer who backs out is sent. The hosted page renders a link to it, but only before the split is set up. See below.
currencyNoDefaults to gbp. gbp is the only accepted value today. More currencies will be added, so treat currency in responses and webhooks as an open list of lower-case ISO 4217 codes rather than assuming gbp.
line_itemsNoWhat the order is made of, shown to everybody who is asked to pay. See below.
customer_emailNoThe buyer's address, if you know it. When they choose to split, we send their code straight away instead of asking them to type the address and press a button. If it belongs to a SharePay account with a verified phone, the code goes by text ("Welcome back. We texted a code to your phone ending 67."); otherwise by email. They can still say "Not you?" and use another address, and nothing is shared until the code is entered.
customer_nameNoUp to 120 characters. Stored and echoed back to you, never shown to the group.
metadataNoYour own ids, as a flat object of strings: up to 20 keys, keys up to 40 characters, values up to 500, 4 KB in all (the same limits as Stripe). Echoed back on the status endpoint and in every webhook for the order. Never shown to anyone paying.
allow_reviewNotrue offers your customer "Send it to someone to review". Defaults to false. Sending for review keeps the session open for 72 hours. See Send for review.

Retrying safely​

Send an Idempotency-Key header (any string up to 255 characters, your order id is the obvious choice) and a retry cannot create a second checkout for the same order:

POST /api/merchants/checkout/sessions
x-merchant-api-key: sp_prod_...
Idempotency-Key: order-1042
  • The same key with the same body inside 24 hours returns 200 with the original token and checkout_url. Nothing new is created.
  • The same key with a different body returns 409 { "code": "idempotency_key_reused" }. That is a bug on your side: pick a new key for a new order.
  • After 24 hours the key is forgotten and may be reused.

Without the header every call creates a new session, as before.

What your customer sees​

They choose how to pay, and none of the routes require a SharePay account: split it with other people, ask one person to pay the whole thing, or pay it themselves. Signing in is offered but never required.

This is worth knowing if you integrated earlier: a login wall used to be the first thing your customer met on that page, and it is gone.

Customers pay no SharePay fee. One payer, whichever route they took, pays the order total and nothing more, and each person in a split pays their share and nothing more.

If your account cannot take payments when they try, they read "This shop can't take payments right now." and nothing about why. The response carries the reason as a code: billing_card_required (add a card in Settings, Billing), billing_paused (pay the unpaid SharePay bill there) or connector_not_live. We are alerted when this happens to a live customer.

Send for review​

Some customers want somebody else to look at the basket before they pay: a partner checking sizes, a parent checking a child's order. Send allow_review: true when you create the session and the hosted page offers "Send it to someone to review" alongside the other ways to pay.

  1. Your customer enters their own email and the reviewer's.
  2. We email the reviewer a link to the basket: every line, quantity, price and picture, and the total. They are told they are not being asked to pay.
  3. The reviewer approves it or suggests changes, with an optional comment.
  4. We email your customer a link back to the same checkout, where the answer and comment are shown above the ways to pay.

A few things to know:

  • It keeps the checkout open longer. Once a customer sends it for review the session lasts at least 72 hours from then, instead of the usual two, so checkout_session.expired arrives later for that order. That is why it is off unless you turn it on.
  • It never blocks payment. The customer can pay at any time, before or after the reviewer answers. The session's status does not change and no new webhook is sent.
  • Put sizes and colours in description. The reviewer sees exactly the lines you send, so "Oxford shirt, M, navy" is far more useful than "Shirt". Send line_items too, or the reviewer sees only a total.
  • The basket cannot be edited from the review. If the reviewer suggests changes, your customer changes the basket on your site and checks out again, which creates a new session.
  • Not offered on decline recovery sessions.

Telling payers what they are buying​

Send line_items and every payer sees the order itemised: the buyer on the hosted page, and anyone they invite to pay a share. Leave it out and nothing changes from before.

This matters most for the people you never meet. Somebody sent a payment link has no basket and no account, so without line items all they see is a reference code and an amount, and they are being asked for their card on that basis.

FieldRequiredNotes
descriptionYesUp to 120 characters. Shown as written.
amountYesPounds, not pence, like the order amount. Negative for a discount.
quantityNoA whole number of 1 or more.
image_urlNoAn https URL we fetch once and re-serve. See below.

The lines must add up to amount, or the call fails with 400. Delivery, tax and discounts are simply more lines, and a discount is a negative one. This is deliberate: a payer has no way to check an itemisation against the amount being taken from their card, so we check it for you.

There is no limit on how many lines you send. The request as a whole is capped in size, so a very large basket may need shortening; a long list is displayed with the first few lines and a count of the rest.

Everything you send here is shown to strangers on a page that asks for card details, so it is rendered as plain text. Markup, links and scripts in a description appear as the characters you typed, and are never followed.

Pictures​

We do not hot-link your image. When you create the session we fetch image_url once, check it really is an image, and serve our own copy from then on. Your server therefore never sees the people paying, which matters because some of them are people your customer invited and who have no relationship with you at all.

Send a publicly reachable https URL, 2 MB or smaller, as PNG, JPEG, GIF, WebP or AVIF. SVG is not accepted. Up to a dozen pictures per order are taken, and we give up on a slow host quickly.

A picture we cannot fetch is simply left out. The line keeps its description and price and the checkout works normally: a thumbnail is never a reason to fail somebody's purchase. If your images are behind a signed URL or a firewall, expect them not to appear.

cancel_url is only offered before the split exists

When you send one, the hosted page renders a Cancel and return to <your business name> link below the card, and the session lookup returns the value as cancel_url. Omit the field and no link is rendered at all: the page does not fall back to return_url, because this flow only ever sends a buyer to return_url on success and a merchant handler reading that hit could book an order that was never placed.

The link only appears while the buyer is still signing in or choosing shares. It disappears the moment the split is created. From that point every participant has a card hold against them, and a link that merely walks back to your shop would read as "this releases the holds" when it does not. Unwinding a live split is cancel or refund, not navigation.

So a hit on your cancel_url means "the buyer walked away before placing anything", and it is the only case you will hear about. A buyer who authorises their share and then abandons the split sends you nothing, and neither does one who closes the tab. Do not treat cancel_url as an abandonment feed. Reconcile on the token instead: a session that never produces a split, or a split that never reaches checkout_split.paid, is the real signal. See Reconciling without a webhook.

This endpoint takes pounds, not pence

"amount": 12000 is read as £12,000 and rejected, because it is over the £5000 ceiling. A £120 order is "amount": 120.

The direct POST /api/checkout-splits endpoint is the other way round: it takes each participant's amountMinor in pence. The two endpoints do not share a unit.

Set your allowed return domain first​

allowed_domain must be set on your account before this call will succeed. Set it on the Developers page in your dashboard, under "Allowed return domain". While it is unset, every return_url is rejected.

The check, for both return_url and cancel_url, is:

  • The URL must parse, and its scheme must be https:.
  • Its hostname must equal allowed_domain, compared case-insensitively.
  • The path, port and query string are not checked. With an allowed domain of your-shop.example, both https://your-shop.example/order/complete and https://Your-Shop.example:8443/anything?x=1 pass.
  • Subdomains are not covered. https://shop.your-shop.example/... does not match an allowed domain of your-shop.example.

cancel_url is only checked when you send one.

When the call returns 400​

ResponseCause
Only gbp is supportedcurrency was set to anything other than gbp.
amount must be between £1 and £5000amount was outside that range, or was not a number. Remember it is in pounds.
return_url must be https and match your allowed return domainNo allowed_domain set, or the URL failed the hostname check above.
cancel_url must be https and match your allowed return domainSame check, on the cancel_url you sent.
Connect a payment processor before accepting checkoutsNo processor is connected yet. Connect Stripe or Adyen: see Connect your payment provider.
Finish Stripe onboarding before accepting checkoutsYou started connecting Stripe, but your account is not stripe_charges_enabled yet. See Connect Stripe.

An invalid or missing API key returns 401 Invalid API Key.

This endpoint is limited to 120 requests a minute, keyed by your API key, and returns 429 Too many checkout session requests. Please slow down. beyond that. RateLimit-* headers are on every response.

If the request times out, do not retry blindly

This endpoint cannot tell a retry apart from a new request, and there is no key you can send to make it. Send it twice and you get two sessions for one basket.

A session on its own is harmless, since it holds no money. The damage is that a buyer handed two live sessions can set up two splits, and place two sets of card holds on their friends. So save the token against your order as soon as you get it, and if one is already there, reuse it instead of making another.

2. Redirect the buyer​

Redirect the buyer to checkout_url. SharePay hosts the buyer-facing page, where they sign in and set the split up: inviting participants and choosing amounts. The split itself is created there, not by your API-key call. The buyer returns to your return_url when they are done.

On that page the buyer may split with at most 20 people, and their chosen shares must add up exactly to the session amount. A split can only be set up once per session: a second attempt gets 409 This checkout already has a split.

Each share must be at least £1. A buyer who gives someone less gets 400 Each share must be at least £1. on the hosted page and nothing is created. That also caps how many ways a small order can go: a £15 order cannot be split more than 15 ways, whatever the 20-person limit says.

Each participant is then charged their share and nothing more, shown to them before they authorise. Customers pay no SharePay fee. Your amount is the order share before SharePay's merchant fee and Stripe's processing fees. See what SharePay charges.

Until they create the split, the page also offers a way back to your cancel_url, if you sent one. Once the split exists that link is gone, and so is any signal to you that the buyer changed their mind.

Choose how buyers pay​

Create the session on your server as above. Then pick one of three ways to show checkout. All three use the same token.

ModeWhat happens
RedirectThe buyer goes to checkout_url and returns to your return_url.
EmbeddedCheckout loads in an iframe on your page.
PopupCheckout opens in a small window over your page.

For embedded and popup, load sharepay.js from the same site as your checkout_url. With keys from share-pay.co.uk, test or live, that is:

<script src="https://share-pay.co.uk/js/v1/sharepay.js"></script>

In the sandbox (demo.share-pay.co.uk), load https://demo.share-pay.co.uk/js/v1/sharepay.js instead. Test keys run on the same site as live keys; only the sandbox is a separate site. The Developers page shows snippets with the right script for the site you are on.

Embedded​

<div id="sharepay"></div>
<script>
var checkout = SharePay.mount("#sharepay", {
token: token,
appearance: { theme: "light", accent: "#14213d", radius: 8, font: "IBM Plex Sans" },
onReady: function () {},
onComplete: function (result) { /* result.order, result.outcome */ },
onCancel: function () {},
onError: function (err) { /* err.code, err.message */ }
});
// checkout.destroy() removes the iframe.
</script>

mount throws if the target is missing or token is empty. Embedded mode is guest only. Google Pay and cards stay in your page. Apple Pay opens a small SharePay window. If the buyer's bank sends them to its own page to confirm a payment, that takes the whole tab, and the bank brings them back to a SharePay page, not to yours.

Embedded checkout is drawn as part of your form, with no order summary, because your page already shows the basket. By default it is SharePay branded, so buyers recognise it: a green SharePay header over a light green panel. Set an accent and it is drawn in your colour instead, with no background of its own, so it sits on your page. Either way, under it is a small "Cancel and return" link (only when the session has a cancel_url) and "Secured by SharePay".

Appearance​

Every option is optional. Anything not understood is ignored, never an error.

OptionValuesDefault
theme"light" or "dark". Match your page."light"
accentA hex colour, "#14213d" or "#fa0". Buttons, links and focus rings use it, and the SharePay header and green panel are dropped. Text on buttons turns white or black to stay readable.SharePay green, branded
radiusCorner radius in pixels, 0 to 24, for fields and buttons.Rounded fields, pill buttons
font"system" for the device's own font, or the name of a Google Fonts family, such as "IBM Plex Sans". Letters, digits and spaces only.Geist

The card fields follow the same accent, radius and font.

sharepay.js builds the iframe URL itself. Do not build or change it: an embed URL with any extra %-encoded or ; query values is refused, and the checkout will not load in your page.

button.addEventListener("click", function () {
var checkout = SharePay.open({
token: token,
onComplete: function (result) {},
onCancel: function () {},
onError: function (err) {}
});
// checkout.close() closes the popup.
});

Call open directly from a click. It throws if token is empty. If the browser blocks the popup anyway, the script sends the whole page to the checkout instead, as in redirect mode, and calls no callback.

While the popup is open, your page shows an overlay that says "Finish paying in the SharePay window", with Reopen window and Cancel buttons. Cancel closes the popup and calls onCancel. When the buyer finishes or cancels inside the popup, the popup closes itself. The script learns the result by polling:

GET /api/merchants/checkout/sessions/<token>/state

It returns { status, outcome, order, return_url, cancel_url, cancelled_at }. CORS allows your allowed domain only. Polling starts as the popup opens and runs every 2 seconds, then every 10 seconds after 2 minutes. A buyer who presses Cancel inside the popup reaches onCancel within a poll interval (2 seconds, or 10 seconds after two minutes): the popup tells SharePay, cancelled_at changes, and the script closes the overlay. The session stays open, so the buyer can still pay from it later. If the same answer says the buyer finished, onComplete wins.

Callbacks​

CallbackReceivesWhen
onReadynothingThe embedded checkout has loaded. Embedded only.
onComplete{ order, outcome }The buyer finished their part.
onCancelnothingThe buyer backed out.
onError{ code, message }Something stopped checkout.

outcome is "held" when the buyer's own share is held. It is "pending" when the buyer's part is done but others still have to pay, or they asked someone else to pay.

If you give no handler, the script does this:

  • held: goes to your return_url with status=success&order=....
  • pending: goes to your site's origin.
  • cancel: goes to your cancel_url, if you set one, when the buyer cancels inside the frame or the popup. The popup overlay's own Cancel without an onCancel just closes the popup and leaves your page as it is.

Error codes:

  • embed_unavailable (embedded only): checkout did not report ready within 15 seconds. Check your allowed domain, and that your page may frame SharePay.
  • session_expired (popup only): the session has expired. Create a new one.
  • state_unavailable (popup only): five status checks in a row failed, for example an unknown token or a Content Security Policy blocking the request. The overlay is removed and polling stops.

Browser callbacks are for the interface only. Fulfil the order on the checkout_split.paid webhook, never on onComplete.

Requirements on your site​

  • Set your allowed domain on the Developers page. Embedded and popup only work on a page whose host is exactly that domain. www.shop.example and shop.example are different domains: set the one your checkout page is on.
  • If you use a Content Security Policy, allow the site you load sharepay.js from (https://share-pay.co.uk, or https://demo.share-pay.co.uk in the sandbox) in:
    • script-src
    • frame-src
    • connect-src: popup polling, checkoutShown, and embedded mode when you leave out onComplete or onCancel (the script then fetches your return and cancel URLs from SharePay).
  • Do not sandbox the iframe. If you must, include allow-scripts allow-popups allow-same-origin allow-forms allow-top-navigation-by-user-activation. The script sets allow="payment" for you.
  • If your page also loads the old sharepay-sdk.js, load it before sharepay.js, or drop it. sharepay.js adds mount, open and checkoutShown to the existing SharePay object.

Count your checkouts​

Your dashboard Overview can show what share of your checkouts are paid with SharePay: checkouts with SharePay offered, how many buyers chose it, and how many paid. SharePay only hears about a checkout once a buyer chooses it, so for the first number your checkout page has to tell us. Call SharePay.checkoutShown() once on your checkout page, wherever SharePay is offered:

<script src="https://share-pay.co.uk/js/v1/sharepay.js"></script>
<script>
SharePay.checkoutShown({ merchant: "YOUR_MERCHANT_ID" });
</script>

Your Merchant ID is in the snippet on the Developers page. Add test: true to count test checkouts separately from live ones.

What it sends:

  • One POST per page, with your Merchant ID and the mode. No body, no cookies, nothing stored on the buyer's device and no buyer details.
  • It is counted only when the page's origin is your allowed domain, with or without www.. Calls from anywhere else are ignored.
  • A buyer who reloads the page within 30 minutes is counted once. Our server uses the IP address in memory for that and never stores it. We store a daily total.
  • "Chose SharePay" on your Overview counts only checkouts opened by a buyer counted on your page in the 30 minutes before. Checkouts from pages that do not call checkoutShown are left out, so the share is never inflated by pages you do not count.
  • It never throws once your Merchant ID is valid, and a failed send never affects checkout.

If you use a Content Security Policy, connect-src must allow the site you load sharepay.js from. Section 6 of the Merchant Agreement covers how we use the counts. Because the count comes from your customer's browser, name SharePay in your own privacy notice as a provider on your checkout page.

Apple Pay and Google Pay​

Apple Pay and Google Pay now appear on SharePay pay pages automatically.

  • Stripe merchants: nothing to do.

  • Adyen merchants: do one of these.

    • Give your API key the "Management API: Payment methods read and write" role. We then add our Apple Pay domains for you.
    • Or add share-pay.co.uk and sharepay.org.uk yourself in your Adyen Customer Area.

    Apple Pay and Google Pay must also be enabled on your Adyen account.

To stop offering either wallet, open Developers in the SharePay dashboard and clear Offer Apple Pay or Offer Google Pay under Wallets. It saves as soon as you change it and applies to every checkout, pay link and popup from then on, in test and live mode. Both are on unless you turn them off, and buyers still pay by card either way.

3. Store the token​

token is not just an ingredient of checkout_url. It is the only handle your server has on the order afterwards:

GET /api/merchants/checkout/sessions/<token>/status
x-merchant-api-key: sp_prod_...

returns the whole order as your server sees it: the session, your customer_email, customer_name and metadata, and once the buyer has set the split up, a split block with its status, who has approved, and each participant. The full response, what each status means and how to poll it are in Reconciling without a webhook.

Save token against your own order record at creation time, and treat it as a secret: the credential-less lookup the hosted page uses (GET /api/merchants/checkout/sessions/<token>, no /status) exposes the order amount, your business name and the buyer's email to anyone holding it.

4. Nudge the group​

A group order dies quietly when one friend forgets. From your server:

POST /api/merchants/checkout/sessions/<token>/remind
x-merchant-api-key: sp_prod_...

emails everyone who has not yet approved their share, with their own pay link. Returns { reminded, skipped, next_allowed_at }.

  • Each participant hears at most once every 12 hours, whoever asks.
  • Each order gets three reminder calls in all; after that the call returns 429 { "code": "session_cap_reached" }.
  • When there is nobody left to remind (no split yet, everyone has approved, the order is paid, or the holds have lapsed) it returns 409 { "code": "nothing_to_remind" }.
  • Anyone who has asked us to stop emailing them is skipped, and counted in skipped.

If your thank-you page has a "nudge the group" button, have it call your own server, which calls this with your API key. There is no buyer-side credential for it: the hosted page's guest session never reaches your page, and it lapses two hours after checkout in any case.

Separately, once a day we remind anyone still pending on an order whose card holds lapse within the next 24 hours, whether or not you called this.

Refunds on hosted checkout​

Your server can refund an order it took through hosted checkout, in full or in part, with your API key:

POST /api/merchants/checkout/splits/<split_id>/refund
x-merchant-api-key: sp_prod_...
Content-Type: application/json

{ "amount": "12.50", "reason": "One item out of stock", "idempotency_key": "refund-1042-1" }

split_id is the split.id on the status endpoint and the data.split_id of every webhook for the order. Send no amount to refund everything still outstanding.

  • A partial amount is spread across the people who paid, in proportion to what each still has outstanding, to the penny. Each becomes its own Stripe refund on your account.
  • On a split created before the customer fee was removed, the customer's 20p service fee comes back with the slice that completes their share, in the same Stripe refund, and never out of your balance. Until a share is complete its fee stays with SharePay. Newer splits carry no customer fee.
  • A failure part-way is reported as exactly that. Refunds are issued one participant at a time and are real the moment Stripe accepts them. If Stripe refuses one, the response is 409 partial_failure with what went through and who failed; call again for the remainder.
  • Send idempotency_key (any string up to 255 characters, unique per refund you intend) and a retried call returns the stored result instead of refunding twice.

The full response, the history on the status endpoint and the checkout_split.refunded event are in Refunds, disputes and order status.

Cancelling before capture is still a dashboard operation: POST /api/checkout-splits/:id/cancel takes a signed-in session, not an API key. The dashboard's own Refund button refunds the whole order only.

A worked example​

A minimal server-side handler that turns a basket into a SharePay checkout and redirects the customer:

// POST /checkout/sharepay on your own server
app.post("/checkout/sharepay", async (req, res) => {
const basket = await loadBasket(req.session.basketId);

const response = await fetch(
"https://api.share-pay.co.uk/api/merchants/checkout/sessions",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-merchant-api-key": process.env.SHAREPAY_API_KEY,
},
body: JSON.stringify({
// Pounds, not pence, on this endpoint. £1 to £5000.
amount: basket.totalPence / 100,
order_reference: basket.orderReference,
return_url: "https://your-shop.example/order/complete",
// Where the "Cancel and return" link on the hosted page goes. Only
// offered before the buyer sets the split up, so a hit here means an
// untouched basket, never an abandoned split.
cancel_url: "https://your-shop.example/basket",
}),
},
);

if (!response.ok) {
const { error } = await response.json().catch(() => ({}));
return res.status(502).send(error ?? "Could not start SharePay checkout");
}

const { checkout_url, token } = await response.json();

// Keep the token: it is how you look this order up later, and the only
// split-state surface reachable with an API key.
await saveSharePayToken(basket.orderReference, token);

res.redirect(303, checkout_url);
});

When the buyer lands back on your return_url, treat it as "the split has been set up", not "the money has arrived". Wait for the checkout_split.paid webhook before you fulfil the order, and reconcile on the token for any order that never produces one.

A complete integration, including signature verification and fulfilment, is published as a reference storefront. See Testing.