ShopEazydevelopers
API referenceStorefront APICheckout

Open a hosted checkout for the order's balance

Credentials
  • Store key
Scopes
checkout:write
Idempotency
Send an optional Idempotency-Key header. A retry with the same key does the work once.
POST
/v1/store/orders/{id}/pay

Goes through whichever provider the merchant activated (Yoco, iKhokha or Peach). Send the shopper to the returned url.

Return URLs must be absolute and https (http://localhost is allowed for development). Peach renders its form inside your own page, so pass checkoutPageUrl when the store is on Peach. The checkout is opened with your site's origin (from checkoutPageUrl, else successUrl); for Peach that domain must be on the merchant's allowlist.

Settlement is the platform's job: iKhokha and Peach call back to this API, Yoco to ShopEazy's own webhook. Use POST /v1/store/orders/{id}/confirm on your success page.

Old path, deprecated, sunset 1 Feb 2027: POST /v1/orders/{id}/pay.

Authorization

storeKey checkout:write
headerAuthorizationBearer <sez_pub_... (publishable) or sez_sk_... (secret)>

A per-store key from the console. Publishable keys are browser-safe; secret keys are server-only.

Scope: checkout:write

Path Parameters

id*string

The order id returned at placement.

Header Parameters

Idempotency-Key?string

Optional. Mint it once per order or payment attempt and reuse it on every retry: the work is done once and a retry gets the first 2xx response back with Idempotent-Replay: true. Belongs to the store key, remembered 24 hours. The same key with a different method, path or body is 409 idempotency_key_reused; a request still running is 409 in_flight; a malformed key is 422 validation_error; if the key store cannot be read nothing is processed and the answer is 503 idempotency_unavailable.

Match^[A-Za-z0-9_-]{8,128}$

Request Body

application/json
  1. body
successUrl*string

Where the shopper lands after paying. Absolute https.

Formaturi
cancelUrl*string

Where they land if they back out. Absolute https.

Formaturi
failureUrl?string

On failure. Defaults to cancelUrl.

Formaturi
checkoutPageUrl?string

Peach only. The page on your site that mounts the payment widget.

Formaturi

Response Body

The checkout to send the shopper to.

application/json
  1. response
data*
Example Request
curl -X POST 'https://api.shopeazy.co/v1/store/orders/<id>/pay' \  -H 'Authorization: Bearer sez_pub_...' \  -H 'Idempotency-Key: <unique_key>' \  -H 'Content-Type: application/json' \  -d '{  "successUrl": "https://example.com",  "cancelUrl": "https://example.com"}'
Example Response
{  "data": {    "provider": "string",    "url": "string",    "checkoutId": "string"  }}

An order and its payment status GET

The id alone is not enough. Send the order's `accessToken` from `POST /v1/store/orders` as `X-Order-Token`, or the shopper who placed it. Neither: `401 order_access_required`. A credential for a different order or shopper (or an expired token): `404 not_found`, the same answer as an unknown id. Old path, deprecated, sunset 1 Feb 2027: `GET /v1/orders/{id}`.

Ask the provider whether the order is paid, and settle it if so POST

For the success page. The provider's callback to the platform is the primary settlement path; this is the second, independent one. Idempotent and safe to poll: an already-paid order returns at once. The status always comes from the provider; nothing a caller sends can mark an order paid. Takes no body. It returns the order, so it has the same access rule as `GET /v1/store/orders/{id}`: `X-Order-Token` or the shopper who placed it. Old path, deprecated, sunset 1 Feb 2027: `POST /v1/orders/{id}/confirm`.