Embedded modal Payments API

The embedded modal loads the Ozow payment page in an overlay on top of your own page. Your customer never leaves your site, the payment experience appears as a modal dialog while your checkout page remains visible in the background.

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 modal checkout works#

The modal checkout works identically to the iframe checkout with two differences:

1. No container div is required, the modal iframe is injected automatically by the SDK
2. Use createPaymentModal() instead of createPaymentFrame()

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#

The modal checkout only requires two UI elements, a trigger button and a cancel button. No container div is needed.

<!-- Trigger element - customer clicks this to open the modal -->
<button id="payUsingOzow">Pay with Ozow</button>

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

---

Step 4: Initialise the SDK and launch the modal#

Instantiate the SDK and wire up your trigger element to launch the modal 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.createPaymentModal(paymentUrl, postData);
};

The SDK automatically appends ?viewName=JsPopup 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 modal:

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 payment completes, 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 === "ozowHideModal") {
    // e.g. show a "Payment closed" notification
  }
});

---

Error handling#

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

<button id="payUsingOzow">Pay with Ozow</button>
<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.createPaymentModal(paymentUrl, postData);

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

---

Next steps#

• Review the Building a secure integration checklist before going live
• Test your integration using Payin test cases
• See the Payments API reference for the full technical specification
• Looking for digital wallets or card? See the Wallet SDK