Name: PayShare Group Checkout
Brand: PayShare
Availability: OnlineOnly

Error format

Start-split and refund errors share one shape. Branch on error.code. The message is safe to log but may change, so do not match on it.

Error response

{
  "success": false,
  "error": {
    "code": "WEBSITE_SETUP_REQUIRED",
    "message": "Split unavailable",
    "details": { "unavailableLabel": "Split unavailable" }
  }
}

Some errors include details.unavailableLabel, a short message you can show on the button. Validation errors include details listing the fields at fault.

Install and setup

Code	HTTP	Meaning	What to do
`MERCHANT_NOT_INSTALLED`	403	PayShare is not installed on this Stripe account, or was removed.	Check stripeAccountId, or install PayShare.
`WEBSITE_SETUP_REQUIRED`	403	Setup is not confirmed in PayShare. For platform-managed checkout, the platform has not turned PayShare on yet.	Confirm set up in the PayShare app, or finish connecting your platform.
`PLATFORM_SPLIT_OFF`	403	The platform that runs this checkout has turned Split off for this merchant.	Hide the button. Contact the platform.
`PLATFORM_CHECKOUT_PAUSED`	403	PayShare has paused new splits for this checkout.	Hide the button and try later.

Request

Code	HTTP	Meaning	What to do
`INVALID_INPUT`	400	The body failed validation: a missing, wrong or unknown field, or both or neither of checkoutExpiresAt and checkoutHold.	Fix the fields listed in details.
`INVALID_ACCOUNT`	400	stripeAccountId is not a Stripe account ID.	Send the acct_ ID of the install account.
`INVALID_PROOF`	400	paymentIntentId is not a PaymentIntent ID.	Send the pi_ ID of your order proof.
`SUCCESS_RETURN_URL_REQUIRED`	400	successReturnUrl is missing.	Send an HTTPS success URL.
`RETURN_URL_REJECTED`	400	A return URL is not a valid HTTPS URL.	Send absolute HTTPS URLs.
`ORDER_SUMMARY_INCOMPLETE`	400	orderSummary is missing merchantDisplayName or itemDescription.	Send both.
`SETTLEMENT_ACCOUNT_FORBIDDEN`	403	platformContextId names a Stripe account that cannot receive this split.	Remove it, or send a connected account of the install account.

Order proof

Code	HTTP	Meaning	What to do
`PROOF_NOT_FOUND`	404	The PaymentIntent does not exist on the install account.	Create the proof with the install account’s key.
`PROOF_INELIGIBLE`	400	The PaymentIntent cannot start a split: wrong status, missing PayShare metadata, no amount or currency, a test and live mismatch, or it was already used.	Create a new, unconfirmed proof with the required metadata in the same mode as the install.
`BELOW_MIN_SPLIT_AMOUNT`	400	The order total is below the minimum for a split. details.minSplitAmountMinor gives the minimum.	Hide the button for this order.

Checkout hold

Code	HTTP	Meaning	What to do
`CHECKOUT_EXPIRED`	400	checkoutExpiresAt has already passed.	Refresh the hold, or send checkoutHold: "none".
`CHECKOUT_EXPIRY_TOO_CLOSE`	400	The hold ends in 30 seconds or less.	Extend the hold before starting a split.
`CHECKOUT_EXPIRY_INVALID`	400	checkoutExpiresAt is not a valid timestamp, or is further out than PayShare allows.	Send an ISO 8601 time with an offset, within the maximum in the message.

Refunds

Code	HTTP	Meaning	What to do
`SESSION_NOT_FOUND`	404	No session with that ID for this install.	Check the session ID and Stripe account.
`REFUND_TOKEN_INVALID`	403	The refund token does not belong to this session.	Use the token from that session’s start-split response.
`REFUND_FAILED`	400	Stripe did not accept the refund.	Read the message, or refund from the PayShare app.

Secret key and account id

This failure happens on your server, before PayShare sees the request. Stripe returns: The provided key does not have access to account.

STRIPE_SECRET_KEY is the login. The acct_ you pass as stripeAccountId, or as the Stripe-Account header when you create the order proof, is the shop. Swapping only the secret key leaves the old account id in the start-split route. The new key cannot charge that old account, and the button shows PayShare — unavailable. Update the account id to the acct_ that owns the new key. Pay now and Split must use that same account.

Availability

Code	HTTP	Meaning	What to do
`RATE_LIMITED`	429	Too many requests from your server.	Back off and retry.
`BOOTSTRAP_DISABLED`	503	Starting splits is temporarily unavailable.	Hide the button and retry later.
`STRIPE_CONNECTOR_NOT_CONFIGURED`	503	PayShare cannot reach Stripe for this mode right now.	Retry later.
`DATABASE_UNAVAILABLE`	503	A temporary PayShare outage.	Retry with backoff.