## 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

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

## Example 2

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

## Related guides

- [Accept payments](/docs/payment-api/accept-payments/)
- [Payment lifecycle](/docs/general/payment-lifecycle/)
- [Webhook events](/docs/payment-api/webhooks/)
- [Hosted checkout](/docs/payment-api/hosted-checkout/)

## Iframe markup

```html
<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

```js
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

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

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

```bash
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": {} }
  }'
```