EnsureBack Docs

Protected Checkout

Create Stripe Checkout Session on the merchant’s connected Stripe account, while EnsureBack binds a policy snapshot for escrow lifecycle.

View OpenAPIBack
Try it
Calls POST /api/public/protected-checkout from this domain and opens the returned Stripe Checkout URL in a new tab.
Stored locally in your browser (localStorage) for convenience.
Host must match origin host: localhost:3000
Host must match origin host: localhost:3000
Line items
Origin host: localhost:3000
Last response
{}
Expected backend behavior
  • Validate API key (Bearer or x-api-key).
  • Check Origin host against merchant website whitelist.
  • Enforce successUrl/cancelUrl host == Origin host.
  • Resolve merchant active policy + version snapshot.
  • Create Stripe Checkout Session on merchant connected account.
Endpoint
POST /api/public/protected-checkout

Returns a Stripe Checkout URL. You redirect the buyer to that URL.

cURL
bash
curl -X POST \
  -H "Authorization: Bearer <ENSUREBACK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [{"price":"price_123","quantity":1}],
    "successUrl":"https://YOUR_DOMAIN/test-merchant/success",
    "cancelUrl":"https://YOUR_DOMAIN/test-merchant/cancel",
    "orderRef":"ORDER_123",
    "customerEmail":"buyer@example.com"
  }' \
  https://YOUR_DOMAIN/api/public/protected-checkout
Node (server)
js
const res = await fetch("https://YOUR_DOMAIN/api/public/protected-checkout", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.ENSUREBACK_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    lineItems: [{ price: "price_123", quantity: 1 }],
    successUrl: "https://YOUR_DOMAIN/test-merchant/success",
    cancelUrl: "https://YOUR_DOMAIN/test-merchant/cancel",
    orderRef: "ORDER_123",
    customerEmail: "buyer@example.com"
  })
});

const json = await res.json();
if (!res.ok) throw new Error(JSON.stringify(json));
console.log(json.checkout.url);
Rules
text
Key rules:
- API key must be valid (Bearer or x-api-key).
- Request must include Origin (browser) or Referer.
- Origin host must be whitelisted in Merchant panel (Websites).
- successUrl and cancelUrl MUST be on the same host as the whitelisted Origin host.
- Server resolves the merchant's ACTIVE policy + version snapshot automatically (MVP).
Common errors
  • api_key_missing / api_key_invalid: Missing/invalid API key.
  • origin_missing: Call made without Origin/Referer (typically server mis-call).
  • domain_not_whitelisted: Origin host not registered in Merchant → Developer → Websites.
  • redirect_host_mismatch: successUrl/cancelUrl host does not match the whitelisted origin host.
  • stripe_account_not_connected: Merchant has no connected Stripe account id in EnsureBack.