Accept payments anywhere with one API call.

Choose your integration

Three ways to take a payment, same payment-request engine underneath. Pick by how much control you need over the checkout UI versus how little code you want to write.

Not sure? Start with hosted redirect, it is the fastest to ship and you can move to the embedded iframe later without changing how you create or settle requests.

Keep the buyer on your own domain. Instead of redirecting to the hosted page, render the embed_url from a payment request in an iframe inside a popup, with the payer's details prefilled. Both wallet and card show by default, same as a direct visit to the hosted page, buyer picks. Your server never touches card data, the iframe is served by Payclio and stays at SAQ-A scope.

1. Build the popup

A button that opens a modal on click, not an always-visible iframe, so nothing loads (or sits blank) until the buyer actually wants to pay. Lazy-load the iframe src from the embed_url returned by POST /payment-requests (it already carries ?embed=1) plus the prefill params below, and show a loading state until the frame's load event fires. The allow="payment *" attribute is required for 3-D Secure inside the frame.

<!-- A button that opens the checkout in a popup, not an always-visible
     iframe: nothing loads (or shows a blank white box) until the buyer
     actually asks to pay. Wallet and card both appear, buyer picks. -->
<button id="payclio-open" type="button">Pay securely with Payclio</button>

<div id="payclio-modal" style="display:none;position:fixed;inset:0;z-index:100;
     align-items:center;justify-content:center;">
  <div id="payclio-backdrop" style="position:absolute;inset:0;background:rgba(0,0,0,.45)"></div>
  <div style="position:relative;background:#fff;width:100%;max-width:480px;
       max-height:92vh;border-radius:16px;overflow:hidden;display:flex;flex-direction:column;">
    <div style="display:flex;justify-content:space-between;align-items:center;
         padding:14px 18px;border-bottom:1px solid #f1f5f9;">
      <strong>Pay securely with Payclio</strong>
      <button id="payclio-close" type="button" aria-label="Close">&times;</button>
    </div>
    <div style="position:relative;flex:1;overflow-y:auto">
      <div id="payclio-loading" style="position:absolute;inset:0;display:flex;
           align-items:center;justify-content:center;background:#fff;">Loading…</div>
      <iframe
        id="payclio-iframe"
        data-src="https://app.payclio.com/req/<token>?embed=1&name=Jane%20Doe&email=jane%40acme.com&phone=%2B264811234567"
        allow="payment *; clipboard-write"
        referrerpolicy="strict-origin"
        style="width:100%;min-height:560px;border:0;opacity:0;transition:opacity .2s"
        title="Secure payment">
      </iframe>
    </div>
  </div>
</div>

<script>
  var open_   = document.getElementById('payclio-open');
  var modal   = document.getElementById('payclio-modal');
  var iframe  = document.getElementById('payclio-iframe');
  var loading = document.getElementById('payclio-loading');

  open_.addEventListener('click', function () {
    modal.style.display = 'flex';
    if (!iframe.src) iframe.src = iframe.dataset.src; // lazy-load on first open
  });
  document.getElementById('payclio-close').addEventListener('click', close);
  document.getElementById('payclio-backdrop').addEventListener('click', close);
  function close() { modal.style.display = 'none'; }

  iframe.addEventListener('load', function () {
    loading.style.display = 'none';
    iframe.style.opacity = '1';
  });
</script>

2. Listen for events, then confirm server-side

The frame posts messages to the parent window. Trust only messages whose origin matches the embed origin and whose data.source === 'payclio'.

// Trust only messages from the embed origin AND source: 'payclio'.
const origin = new URL(embedUrl).origin;

window.addEventListener('message', (e) => {
  if (e.origin !== origin) return;
  const d = e.data || {};
  if (d.source !== 'payclio') return;

  switch (d.event) {
    case 'payment.ready': /* card field rendered */ break;
    case 'payment.paid':  confirmOnServer();        break; // hint only
  }
});

// Authoritative: never fulfil on the browser event alone. Have YOUR server
// re-check status and only then mark the order paid (idempotently).
async function confirmOnServer() {
  await fetch('/checkout/payclio/confirm', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token }),
  });
  // server-side: GET /api/v1/payment-requests/{token} -> mark paid iff status === 'paid'
}

Payment Requests

Each payment request is a one-shot, amount-locked checkout. After it's paid (or expired, or cancelled), it cannot be reused, mint a fresh one for the next order.

Add endpoints under Webhooks in your dashboard. We POST a signed JSON payload when a payment request is paid, expires or is cancelled. Retries on non-2xx and timeouts: 30s, 5m, 30m, 2h, 12h.

Events

Payload

POST https://your-store.com/payclio/webhook
Content-Type: application/json
X-Payclio-Event: payment_request.paid
X-Payclio-Event-Id: evt_a1b2c3d4e5f6g7h8i9j0
X-Payclio-Signature: t=1715600000,v1=8e3a...4f1c

{
  "id": "evt_a1b2c3d4e5f6g7h8i9j0",
  "event": "payment_request.paid",
  "created_at": "2026-05-13T14:00:00Z",
  "data": {
    "token": "a1b2c3d4e5f6g7h8",
    "uuid": "9b1a...",
    "status": "paid",
    "amount": "49.99",
    "currency": "USD",
    "memo": "Order #1234, Acme Store",
    "reference_type": "woocommerce_order",
    "reference_id": "1234",
    "return_url": "https://example.com/checkout/order-received/1234/",
    "paid_at": "2026-05-13T13:59:55Z",
    "paid_by_user_id": 9,
    "transaction_id": 4821,
    "expires_at": "2026-05-13T14:00:00Z",
    "created_at": "2026-05-13T13:00:00Z"
  }
}

Verifying signatures

// PHP: recompute and constant-time compare
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_PAYCLIO_SIGNATURE'] ?? '';
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $header, $m);
[$_, $ts, $sig] = $m;

$expected = hash_hmac('sha256', "$ts.$body", $secret);
if (! hash_equals($expected, $sig)) {
    http_response_code(400); exit;
}

Reject events older than about 5 minutes (replay protection). Respond 2xx within 10 seconds, non-2xx and timeouts trigger the retry schedule above.