SB Checkout API v1 documentation

curl --request POST 'https://SB_CHECKOUT_HOST/api/checkout/v1/sessions' \
  --header 'Authorization: Bearer sbck_test_REDACTED' \
  --header 'SB-Checkout-Version: 2026-08-26' \
  --header 'Idempotency-Key: order_20260825_0001' \
  --header 'Content-Type: application/json' \
  --data '{
    "offerPublicToken": "offer_public_token",
    "quantity": 1,
    "customer": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+351912345678",
      "country": "PT"
    },
    "paymentMethodRequested": "SB_PAY",
    "recoveryConsent": {
      "version": "checkout-recovery-consent-v1",
      "action": "DECLINE",
      "channels": { "email": false, "sms": false, "whatsapp": false }
    }
  }'

// Trusted merchant backend
const response = await fetch("https://SB_CHECKOUT_HOST/api/checkout/v1/payment-intents", {
  method: "POST",
  headers: {
    Authorization: "Bearer sbck_test_REDACTED",
    "SB-Checkout-Version": "2026-08-26",
    "Idempotency-Key": "cart_8f31_payment_intent",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    offerPublicToken: "offer_public_token",
    customer: { firstName: "Ada", lastName: "Lovelace", email: "ada@example.com" },
    allowedOrigins: ["https://shop.example.com"],
  }),
});
if (!response.ok) {
  throw new Error(`Payment Intent failed (request ${response.headers.get("X-Request-Id")})`);
}
const { paymentIntent } = await response.json();

// Return only paymentIntent.clientSecret to the exact allowed browser origin.
// Browser: after loading /checkout/sdk/v1/sb-checkout.js; never expose sbck_*.
const checkout = new SBCheckout({
  clientSecret: paymentIntent.clientSecret,
  apiBase: "https://SB_CHECKOUT_HOST",
});
const methods = await checkout.listPaymentMethods();
if (!methods.length) throw new Error("No payment methods are available");
const intent = await checkout.confirmPayment({
  paymentMethod: methods[0].type,
  idempotencyKey: SBCheckout.createIdempotencyKey("cart_8f31"),
});

<script
  src="https://SB_CHECKOUT_HOST/checkout/sdk/v1/sb-checkout.js"
  integrity="sha384-WpLaTxPMdY5dPRTN1YDIFP3QH7pTtyo54r+aRKWjvphJc7Wpb+R3hhby8hCgGzPD"
  crossorigin="anonymous"
></script>

// Trusted merchant backend only: never expose sbck_* in the browser.
const response = await fetch(
  "https://SB_CHECKOUT_HOST/api/checkout/v1/payment-intents/sbpi_test_ID/refunds",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sbck_test_REDACTED",
      "SB-Checkout-Version": "2026-08-26",
      "Idempotency-Key": "refund_order_1042_attempt_1",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amount: "10.50", reason: "customer_request" }),
  }
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.refund.id, body.refund.status);

import crypto from "node:crypto";

export function verify(rawBody, timestamp, signature, secret) {
  if (!(Buffer.isBuffer(rawBody) || typeof rawBody === "string")) return false;
  if (typeof timestamp !== "string" || !/^(?:\d{10}|\d{13})$/.test(timestamp)) return false;
  if (typeof signature !== "string" || signature.length > 2048) return false;
  if (typeof secret !== "string" || !secret) return false;

  // Current wire format: Unix milliseconds. Accept legacy Unix seconds too.
  // Keep the original timestamp text unchanged in the signed input.
  const sentAt = Number(timestamp) * (timestamp.length === 10 ? 1000 : 1);
  if (Math.abs(Date.now() - sentAt) > 300_000) return false;

  const parts = signature.split(",").map((part) => part.trim());
  if (parts.length > 16) return false;
  const signatures = parts.filter((part) => part.startsWith("v1="));
  if (!signatures.length || signatures.some((part) => !/^v1=[a-fA-F0-9]{64}$/.test(part))) return false;

  const expected = crypto.createHmac("sha256", secret)
    .update(timestamp + ".", "utf8")
    .update(rawBody) // raw Buffer from the HTTP body, before JSON parsing
    .digest();
  return signatures.some((part) => crypto.timingSafeEqual(
    expected, Buffer.from(part.slice(3), "hex")
  ));
}