Checkout SDK

The Checkout SDK is a public browser script that mounts RoxPay checkout on your site. Merchants create payment links with the authenticated API; the shopper UI is handled by the SDK (iframe). Card data never touches your page (PCI SAQ-A).

Load the script

No authentication is required to load the file:

URL	Use
https://checkout-sdk.roxpay.eu/v1/checkout.js	Production
https://checkout-sdk-sandbox.roxpay.eu/v1/checkout.js	Sandbox

<script src="https://checkout-sdk.roxpay.eu/v1/checkout.js"></script>

This exposes window.RoxPay.

Flow

1. Your backend authenticates with JWT and creates a payment link (POST /api/v4/payments/link).
2. Return PaymentUrl to your frontend (never expose API credentials in the browser).
3. Call RoxPay.createCheckout({ checkoutUrl }).mount("#rox-pay") for an embedded checkout.
4. Handle UI callbacks and reconcile the final status with webhooks.

sequenceDiagram
  participant Shop as Merchant page
  participant API as RoxPay API
  participant SDK as checkout.js
  participant FE as Checkout iframe

  Shop->>API: POST /payments/link (Bearer token)
  API-->>Shop: PaymentUrl
  Shop->>SDK: mount(checkoutUrl)
  SDK->>FE: iframe + postMessage
  FE-->>SDK: payment.completed / payment.failed
  SDK-->>Shop: on("complete") / on("error")
  API-->>Shop: webhooks

Create an embedded link

curl -X POST https://app.roxpay.eu/api/v4/payments/link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Purpose": "Order #12345",
    "Amount": 2999,
    "Currency": "EUR",
    "Type": "embedded",
    "SuccessRedirectUrl": "https://yourshop.com/success",
    "FailureRedirectUrl": "https://yourshop.com/failure",
    "CancelRedirectUrl": "https://yourshop.com/cancel",
    "PaymentMethods": ["card", "apple_pay", "google_pay", "bancontact", "ideal", "klarna", "paypal", "pay_by_bank", "sepa_direct_debit"]
  }'

• Type: "embedded" — iframe / Drop-in (also supports klarna/paypal as single-method embedded: PaymentMethods: ["klarna"] or ["paypal"]). pay_by_bank and redirect rails open the bank/issuer flow in the top window when embedded in an iframe (window.top); card and SEPA stay inside the iframe.
• Type: "standard" (or omitted) — full-page hosted checkout. For hosted, simply redirect the shopper to PaymentUrl — no SDK required.

PaymentMethods accepts planet codes (VIS, ECA, BON, INT, KLN, PAP, …) or SDK names (card, bancontact, ideal, klarna, paypal, apple_pay, google_pay). See available payment methods.

Drop-in (iframe)

<div id="rox-pay"></div>
<script src="https://checkout-sdk.roxpay.eu/v1/checkout.js"></script>
<script>
  const checkout = RoxPay.createCheckout({
    checkoutUrl: "PAYMENT_URL_FROM_YOUR_BACKEND",
    locale: "it",
  });
  checkout
    .on("ready", () => console.log("checkout ready"))
    .on("complete", (event) => {
      // event.type === "payment.completed"
      window.location.href = "/success";
    })
    .on("error", (event) => {
      console.error(event.message);
    })
    .mount("#rox-pay");
</script>

Mount options

Option	Type	Default	Description
checkoutUrl	string	required	PaymentUrl from create-link
locale	string	—	Hint language (en, it, …)
paymentMethods	string[]	—	Optional filter hint (card, apple_pay, …)
theme.customCss	string	—	Prefer setting Metadata.custom_css on create-link
height / width	string	720px / 100%	iframe size
allowPayment	boolean	true	Sets allow="payment" for Apple Pay
applePayParentBridge	boolean	true	Parent postMessage fallback for Apple Pay
externalSubmit	boolean	false	Hide pay/submit buttons inside the iframe; call checkout.submit() from your own button

Session helpers

const checkout = RoxPay.createCheckout({ checkoutUrl, locale: "it" });

// Subscribe to events
checkout.on("ready", () => console.log("ready"));
checkout.on("complete", (e) => console.log("completed", e));
checkout.on("error", (e) => console.error("failed", e));
checkout.on("method_change", (e) => console.log("method", e.method));

// Mount / unmount
checkout.mount("#rox-pay");
checkout.unmount();
checkout.destroy();

// Validate and submit programmatically
const { valid, errors } = await checkout.validate();
if (!valid) {
  console.warn("Checkout invalid", errors);
  return;
}
checkout.submit();

Validate before pay

Use validate() when you collect shopper details on your page and want to confirm the Rox Pay payment form is valid before charging:

async function onPayClick() {
  if (!myForm.checkValidity()) return;

  const { valid, errors } = await checkout.validate();
  if (!valid) {
    // errors is a map of field → message, e.g. { cardNumber: "Invalid card number" }
    console.warn(errors);
    return;
  }

  checkout.submit();
}

With externalSubmit: true, all in-iframe pay buttons are hidden — render your own confirm button on the merchant page and call checkout.validate() then checkout.submit():

const checkout = RoxPay.createCheckout({
  checkoutUrl,
  externalSubmit: true,
});
checkout.on("ready", () => console.log("ready")).mount("#rox-pay");

document.getElementById("pay-btn").addEventListener("click", async () => {
  const { valid, errors } = await checkout.validate();
  if (!valid) {
    console.warn(errors);
    return;
  }
  checkout.submit();
});

Hosted redirect

For a full-page checkout you do not need the SDK — redirect the shopper to the PaymentUrl returned by the API:

// PaymentUrl comes from POST /api/v4/payments/link with Type: "standard"
window.location.href = paymentUrlFromApi;

Events and webhooks

Subscribe with checkout.on(event, handler):

Event	Description
ready	iframe loaded
complete	payment completed (event.type === "payment.completed")
error	payment failed / declined (event.type === "payment.failed", event.message, event.code)
method_change	payment method selected (event.method)
validation	result of checkout.validate() ({ valid, errors })

For redirect rails (Klarna, Pay by Bank, iDEAL, Bancontact) the SDK automatically navigates the top window when required. Card and SEPA stay inside the iframe.

Always treat webhooks as the source of truth (especially Klarna / iDEAL, which may stay pending before capture).

Payment methods

SDK id	Notes
card	Visa, Mastercard, and other scheme brands
apple_pay	Safari / iOS; contact Rox to enable it — wallet button on card checkout (same for google_pay inside embedded iframe via allow="payment")
google_pay	Button inside Rox iframe; contact Rox to enable it
bancontact	Code BON, EUR, BE
ideal	Code INT, EUR, NL
klarna	Code KLN; may require capture after pending — hosted shows as tab, embedded supports klarna_only or mixed chooser
paypal	Code PAP; includes Pay Later / Pay in 3 — same chooser as klarna (requires PayPal enabled on Adyen store)
pay_by_bank	Code BANK, EUR/GBP; embedded accordion supported — bank authorisation redirects via window.top
sepa_direct_debit	Code SEPA, EUR; stays inside the embedded iframe

List what the company can offer: GET /api/v4/payments/available-payment-methods.

Apple Pay

1. Use Safari (Mac or iOS) with a card in Wallet.
2. Contact Rox to enable Apple Pay for your domain.
3. Prefer allow="payment" on the iframe (SDK default). Fallback parent bridge is built into checkout.js.
4. Test in sandbox — see Test cards.

Manual iframe vs SDK

You can still embed with a raw <iframe> as in Embedded Checkout. The SDK wraps that path: iframe creation, allow="payment", Apple Pay parent bridge, and typed callbacks — so you do not hand-roll postMessage.

Next steps

• Payment links — full create-link reference
• Payment lifecycle — capture / refund
• Webhooks — reconcile status
• Test cards — sandbox credentials