SPICEPAY DEVELOPER DOCS

Embedded & own checkout

An embedded integration displays the hosted page in an iframe.

◷ 2 min readEnglish · API referenceMarkdown öffnen ↗

How it works

An embedded integration displays the hosted page in an iframe. Your own checkout may instead provide buttons for supported redirect methods, without handling raw card details.

Implementation

Add your exact parent origin to the shop's iframe allowlist. The iframe must permit payments and, for native method panes, popups and escape from a sandbox. Verify the origin and source of payment_status messages and use them to refresh the UI, while webhooks remain authoritative. Wallet visibility depends on processor domain requirements. For a fully custom redirect flow, create and confirm with the appropriate method data and connector routing, then handle the returned next action.

HTTP example

{
  "source": "spicepay-checkout",
  "type": "payment_status",
  "payment_id": "pay_xxxxx",
  "status": "succeeded"
}

Example 2

{
  "payment_id": "pay_xxxxx",
  "status": "requires_customer_action",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": "https://..."
  }
}

Iframe markup

<iframe
  title="SpicePay checkout"
  src="https://checkout.spicepay.net/pay/MERCHANT_ID/PAYMENT_ID"
  width="100%" height="680"
  allow="payment *"
  sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation">
</iframe>

Validate a status message

window.addEventListener("message", (event) => {
  if (event.origin !== "https://checkout.spicepay.net") return;
  if (event.data?.source !== "spicepay-checkout") return;
  if (event.data?.type !== "payment_status") return;
  // Refresh your UI using event.data.payment_id and event.data.status.
  // Confirm the order's paid state on your server before fulfilment.
});

Request examples

<iframe
  src="https://checkout.spicepay.net/pay/mer_xxxxx/pay_xxxxx"
  width="100%"
  height="640"
  allow="payment *"
></iframe>

window.addEventListener("message", (event) => {
  if (event.origin !== "https://checkout.spicepay.net") return;
  if (event.data?.source !== "spicepay-checkout") return;
  showPaymentStatus(event.data.status);
});

curl -X POST https://api.spicepay.net/payments \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order_2042' \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "profile_id": "pro_xxxxx",
    "confirm": true,
    "return_url": "https://shop.example/return",
    "payment_method": "crypto",
    "payment_method_type": "crypto_currency",
    "payment_method_data": { "crypto": {} }
  }'

Fragen zu deiner Integration? SpicePay kontaktieren ↗