Decline recovery

A customer's card is declined at your checkout because there isn't enough money on it. Instead of losing the sale, you send the order to SharePay and the customer is offered two ways to pay it:

• With other people. They pay part now, and send the people they're buying with a link for the rest.
• Across their own cards. Up to four cards, all paid on the same page.

Every share is held on its card, not charged. Once the whole order is covered, every share is charged together and you get one paid order. If it isn't covered within 48 hours, every hold is released and nobody pays.

The money goes to your own payment provider, as with any SharePay split.

Which declines are offered

Only declines where the card works but is short of money. Anything that means the bank is blocking the card is never offered, so a split can't be used to get round a fraud decision.

Decline	ISO code	Stripe decline_code	Adyen refusalReason	Offered
Not enough funds	51	insufficient_funds	Not enough balance	Yes
Over the card limit	61	card_velocity_exceeded	Withdrawal amount exceeded	Yes
Too many withdrawals	65	withdrawal_count_limit_exceeded	Withdrawal count exceeded	Yes
Do not honour	05	do_not_honor	Refused	No
Lost, stolen, suspected fraud	41, 43, 59	lost_card, stolen_card, fraudulent	FRAUD	No
Wrong details, expired card	14, 54	incorrect_number, expired_card	Invalid Card Number, Expired Card	No

Send whatever code your provider gave you. You don't need to filter it first: we tell you whether to show the offer.

Read the decline code on your server

Take the code from your own payment provider's response or dashboard API, never from the browser. A code sent from the customer's page can be changed by the customer, which would turn a fraud decline into a split offer.

1. Ask us when a payment is declined

From your server, with your API key, the moment your provider declines a payment:

POST /api/merchants/checkout/recovery

{
  "amount": 1240.00,
  "order_reference": "SW-48213",
  "decline_code": "insufficient_funds",
  "return_url": "https://your-shop.example/order/complete",
  "cancel_url": "https://your-shop.example/basket",
  "customer_email": "[email protected]"
}

The body is the same as creating a hosted checkout session, plus decline_code. order_reference is required here.

When we'll offer a split (201):

{
  "recoverable": true,
  "token": "6f0c1d2e-...",
  "checkout_url": "https://share-pay.co.uk/checkout/pay/6f0c1d2e-...",
  "hold_hours": 48
}

When we won't (200):

{ "recoverable": false, "reason": "not_recoverable" }

reason is not_recoverable for a decline we don't offer on, or already_offered when this order has already had its one offer. Show your own decline message as usual.

One offer per order. A second call for the same order_reference returns the same checkout_url while the first offer is still open, and already_offered after that. Retrying after a timeout is safe, and you can also send an Idempotency-Key as on sessions; a retry is answered with the offer as it stands now.

A recovery order is always split between at least two people or cards. It can't be paid in full on one card or passed to a single other person.

2. Show the offer

Send the customer to checkout_url, or show a "Split this payment" button that goes there. With the SharePay script on your page:

<div id="sharepay-recovery"></div>
<script src="https://api.share-pay.co.uk/sharepay-sdk.js"></script>
<script>
  // After your own payment fails. recoveryUrl is YOUR server's endpoint: it
  // reads the decline code from your payment provider for this order, calls
  // POST /api/merchants/checkout/recovery and returns the answer.
  SharePay.recover("#sharepay-recovery", {
    recoveryUrl: "/api/payments/recover",
    orderReference: "SW-48213",
  });
</script>

The script shows the offer only when we said yes, and does nothing otherwise.

3. Fulfil on the webhook

A recovered order ends exactly like any hosted checkout: fulfil it on checkout_split.paid. Its payload has "origin": "decline_recovery", so you can count recovered sales. If the order isn't covered in 48 hours you get checkout_split.canceled.

Fees

The customer pays their share and nothing more. You pay the usual 3% of the order, only when the split completes. An offer that isn't taken up, or a split that isn't completed, costs nothing.