Embedded iframe Payments API

The embedded iframe embeds the Ozow payment page directly inside a container on your own page. Your customer never leaves your site, the full payment experience loads inside an iframe within your checkout flow.

This guide is a Payments API integration. You create the payment request with POST /postpaymentrequest, authenticate with your API key, and sign the hash with your private key: the One API Client ID and Client Secret are not used here. Prerequisites and onboarding says which credential belongs to which API.

Not sure which embedded option is right for you? See Choose your integration.

Before you start#

• You have completed Prerequisites and onboarding
• You have your API key, private key, and site codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. from your Ozow Dashboard
• jQuery 1.12.x or higher is required: the Ozow SDK depends on jQuery. Make sure it is loaded on your page before the Ozow SDK script.
• Your notification URLWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API., success URL, cancel URL, and error URL are set up and publicly accessible via HTTPS

How iframe checkout works#

Environments#

---

Core integration#

Step 1: Create a payment request#

Create a payment request server-side using the Payments API. This is identical to the redirectRedirect Sending the payer to the Ozow payment page to complete the payment, and returning them to your site afterwards. The alternative is embedding the checkout in your own page, where the payer never leaves it. integration, follow Steps 1 and 2 in the Redirect: Payments API guide to generate the hash check and post the payment request.

The response returns a url, this is your paymentUrl for the SDK in Step 4.

---

Step 2: Install the SDK#

Add jQuery and the Ozow SDK script to your page. jQuery must be loaded before the Ozow SDK.

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://static-content.ozow.com/scripts/js/v2/ozow-integration-2.0.min.js"></script>

---

Step 3: Add the page markup#

Add a container div where the iframe will be rendered, a trigger element to launch the payment, and a cancel button:

<!-- Container where the iframe will be rendered -->
<div id="paymentContainer"></div>

<!-- Trigger element - customer clicks this to start payment -->
<input type="radio" id="payUsingOzow" value="Ozow" /> Pay with Ozow

<!-- Cancel button -->
<button id="cancelOzowPayment">Cancel Payment</button>

---

Step 4: Initialise the SDK and launch the iframe#

Instantiate the SDK and wire up your trigger element to launch the iframe when the customer selects Ozow as their payment method.

const ozow = new Ozow();

const paymentUrl = "https://pay.ozow.com/"; // Use https://stagingpay.ozow.com/ for staging
const postData = {
  SiteCode: "YOUR_SITE_CODE",
  CountryCode: "ZA",
  CurrencyCode: "ZAR",
  Amount: "100.00",
  TransactionReference: "ORDER-001",
  BankReference: "ABC123",
  CancelUrl: "https://yourstore.com/cancel",
  ErrorUrl: "https://yourstore.com/error",
  SuccessUrl: "https://yourstore.com/success",
  NotifyUrl: "https://yourstore.com/notify",
  IsTest: "false",
  HashCheck: "YOUR_GENERATED_HASH",
};

document.getElementById("payUsingOzow").onclick = () => {
  ozow.createPaymentFrame("paymentContainer", paymentUrl, postData);
};

The SDK automatically appends ?viewName=JsInjection to the payment URL. Your success, cancel, and error URLs are automatically rewritten to /payment/iframeredirect?redirecturl=<ENCODED_URL>; no extra work required on your side.

---

Step 5: Handle cancellation#

Wire up the cancel button to dismiss the iframe:

document.getElementById("cancelOzowPayment").onclick = () => {
  ozow.cancelFramePayment();
};

---

Step 6: Handle the payment outcome#

Ozow sends a notification to your NotifyUrl when the transaction completes. Handle this exactly as described in Step 4: Handle the notification response in the Redirect, Payments API guide, same format, same hash verification process.

After the payment is complete, the SDK automatically redirects the parent page to your SuccessUrl, CancelUrl, or ErrorUrl depending on the outcome.

Optional custom event listener

window.addEventListener("message", (e) => {
  if (e.data?.event === "ozowResize") {
    // Optional custom handling
  }
});

---

Error handling#

If the container ID, payment URL, or post data are invalid, the SDK will:

1. Log a descriptive error message to the browser console
2. Display an alert to the customer: "Payment could not be completed, please contact the site administrator."

Check the browser console for detailed error information during development.

---

Complete example#

<div id="paymentContainer"></div>
<input type="radio" id="payUsingOzow" value="Ozow" /> Pay with Ozow
<button id="cancelOzowPayment">Cancel</button>

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://static-content.ozow.com/scripts/js/v2/ozow-integration-2.0.min.js"></script>
<script>
  const ozow = new Ozow();
  const paymentUrl = "https://pay.ozow.com/";
  const postData = {
    SiteCode: "YOUR_SITE_CODE",
    CountryCode: "ZA",
    CurrencyCode: "ZAR",
    Amount: "100.00",
    TransactionReference: "ORDER-001",
    BankReference: "ABC123",
    CancelUrl: "https://yourstore.com/cancel",
    ErrorUrl: "https://yourstore.com/error",
    SuccessUrl: "https://yourstore.com/success",
    NotifyUrl: "https://yourstore.com/notify",
    IsTest: "false",
    HashCheck: "YOUR_GENERATED_HASH",
  };

  document.getElementById("payUsingOzow").onclick = () =>
    ozow.createPaymentFrame("paymentContainer", paymentUrl, postData);

  document.getElementById("cancelOzowPayment").onclick = () =>
    ozow.cancelFramePayment();
</script>