EnsureBack
Core API Endpoint

Protected Checkout

Create a Stripe Checkout Session on the merchant’s connected Stripe account while EnsureBack binds a policy snapshot for buyer protection, dispute windows, and release logic.

Try endpointView OpenAPI
Method
POST
Path
/api/public/protected-checkout
Auth
Bearer token or x-ensureback-api-key

Try it

Test the endpoint directly from the docs using your API key, line items, and success/cancel URLs. Use current-domain URLs for quick workstation or production validation.

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 for convenience.

Auth header
Host must match origin host: localhost:3000
Host must match origin host: localhost:3000

Line items

Origin host: localhost:3000

Last response

{}

cURL preview

curl -X POST http://localhost:3000/api/public/protected-checkout \
  -H "Authorization: Bearer <ENSUREBACK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "lineItems": [
    {
      "price": "price_123",
      "quantity": 1
    }
  ],
  "successUrl": "http://localhost:3000/test-merchant/success",
  "cancelUrl": "http://localhost:3000/test-merchant/cancel",
  "orderRef": "ORDER_123",
  "customerEmail": "buyer@example.com"
}'

Expected backend behavior

  • Validate API key using Bearer or x-ensureback-api-key.
  • Check Origin host against merchant website whitelist.
  • Enforce successUrl/cancelUrl host against the same origin host.
  • Create a Stripe Checkout Session and return its URL.
  • Bind the active EnsureBack policy snapshot to the protected payment.

Request body

Send this payload from your backend. Do not expose your EnsureBack API key in client-side code.

Request JSON
{
  "lineItems": [
    {
      "price": "price_123",
      "quantity": 1
    }
  ],
  "successUrl": "https://merchant.com/success",
  "cancelUrl": "https://merchant.com/cancel",
  "orderRef": "ORDER_123",
  "customerEmail": "buyer@example.com"
}
lineItems
required

Stripe Price ID and quantity list. Each quantity must be at least 1.

successUrl
required

Redirect URL after successful payment. Host must match the approved origin.

cancelUrl
required

Redirect URL after canceled payment. Host must match the approved origin.

orderRef
optional

Merchant-side order reference shown in dashboards and buyer records.

customerEmail
optional

Buyer email used for protected order visibility and dispute access.

Examples

cURL

Terminal
curl -X POST https://ensureback.com/api/public/protected-checkout \
  -H "Authorization: Bearer <ENSUREBACK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      { "price": "price_123", "quantity": 1 }
    ],
    "successUrl": "https://merchant.com/success",
    "cancelUrl": "https://merchant.com/cancel",
    "orderRef": "ORDER_123",
    "customerEmail": "buyer@example.com"
  }'

Node server

Node / TypeScript
export async function createProtectedCheckout() {
  const response = await fetch("https://ensureback.com/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://merchant.com/success",
      cancelUrl: "https://merchant.com/cancel",
      orderRef: "ORDER_123",
      customerEmail: "buyer@example.com"
    })
  });

  const json = await response.json();
  if (!response.ok || !json.ok) {
    throw new Error(json.error || "protected_checkout_failed");
  }

  return json.checkout.url;
}

Response

A successful response includes a Stripe Checkout URL. Redirect the buyer to that URL immediately.

Success response
{
  "ok": true,
  "checkout": {
    "id": "cs_test_123",
    "url": "https://checkout.stripe.com/c/pay/cs_test_123"
  },
  "protectedPayment": {
    "id": "pp_123",
    "merchantId": "m_123",
    "status": "payment_pending",
    "policyId": "pol_abc",
    "snapshotId": "snap_001"
  }
}

Common errors

api_key_missing
No API key was sent in Authorization or x-ensureback-api-key.
api_key_invalid
The API key does not map to an active merchant.
origin_missing
The request did not provide an Origin or Referer header.
domain_not_whitelisted
The request origin is not registered under merchant websites.
redirect_host_mismatch
successUrl or cancelUrl host does not match the allowed origin host.
stripe_account_not_connected
The merchant has no usable connected Stripe account.
policy_not_found
EnsureBack could not resolve an active policy snapshot.

Next step

After checkout creation works, validate the post-payment lifecycle from the merchant dashboard: payment captured, protected payment visible, buyer dashboard access, dispute entry, and release/refund controls.

Open merchant dashboardOpen buyer dashboard