Embedded wallet Payments API

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.

What is an embedded wallet?#

The embedded wallet lets you offer digital wallets, Apple Pay and Google Pay, and optionally card payments, directly on your checkout page. The payment UI renders inside a secure Ozow iframe on your domain. Your customers never leave your site and sensitive payment data never touches your page.

Not sure which embedded option is right for you? See Overview: how to choose.

Before you start#

Before integrating, confirm the following with Ozow:

• Wallet enablement: Apple Pay, Google Pay, and/or card must be enabled on your merchant profile by Ozow before they will appear
• Origin allowlist: every checkout origin (scheme + host + port) where you will load the SDK must be registered with Ozow. Requests from unlisted origins will receive 403 Forbidden
• Apple Pay domain verification: if you are offering Apple Pay, each top-level checkout domain must be verified (see Apple Pay setup below)
• SettlementSettlement Ozow paying the money you have collected into your bank account. Payins arrive at Ozow first and are settled to you on a schedule, so what a customer paid you today and what has been settled to you today are different amounts. currency: the amount and currency in your payment request must match your Ozow settlement configuration

You will also need:

• An active Ozow merchant account with the relevant payment methods enabled
• A server-side integration to create payment requests
• HTTPS on your checkout domain with a valid TLSTLS The encryption behind https. Every call to Ozow uses it, which is what keeps a request unreadable in transit.Wikipedia certificate

How the Wallet SDK works#

Environments#

---

Core integration#

Step 1: Create a payment request (server-side)#

Your server creates the payment request with POST /postpaymentrequest. The response returns paymentRequestId, a GUIDUUID A 128-bit identifier written as 36 characters, such as 497f6eca-6276-4993-bfeb-53cbbbba6f08. Generated rather than assigned in sequence, so two systems can create identifiers without coordinating.Wikipedia, which you pass to the SDK as its requestId option.

Pass the requestId to your checkout page, typically embedded in the page HTML, returned from your own API, or passed as a query parameter.

---

Step 2: Load the SDK script#

Load the SDK from Ozow's CDN. Contact Ozow for the current recommended version and matching SRI hash for your environment.

<script
  src="https://cdn.ozow.com/sdk/v1/1.7.0/ozow.js"
  integrity="sha384-YOUR_SRI_HASH"
  crossorigin="anonymous"
></script>

---

Step 3: Add the mount container#

Add a container element where the SDK will render the wallet buttons:

<div id="ozow-payment"></div>

No additional markup is required. The SDK injects the iframe automatically.

---

Step 4: Initialise and mount the SDK#

const requestId = "YOUR_REQUEST_ID"; // From your server

const ozow = Ozow.init({
  requestId: requestId,
  environment: "production", // 'test' | 'production'
  apiBaseUrl: "https://pay.ozow.com",
  iframeBaseUrl: "https://pay.ozow.com",
});

// Listen for events before mounting
ozow.on("ready", (payload) => {
  console.log("SDK ready", payload.availableWallets);
  if (payload.availableWallets.length === 0) {
    // No wallets available on this device - show fallback payment methods
    showFallbackPaymentMethods();
  }
});

ozow.on("authorizationResult", (payload) => {
  switch (payload.status) {
    case "approved":
      // Payment authorised - fulfil order using payload.transactionId
      completeOrder(payload.transactionId);
      break;
    case "cancelled":
      // Customer cancelled - re-enable checkout
      unlockCheckout();
      break;
    case "declined":
    case "error":
    default:
      // Payment failed - show message and allow retry
      showPaymentFailed(payload.reason);
      break;
  }
});

ozow.on("error", (payload) => {
  console.error(payload.error.code, payload.error.message);
  showPaymentFailed(payload.error.message);
});

// Mount the SDK
ozow.mount("#ozow-payment", {
  wallets: ["applePay", "googlePay"],
  // To include card when enabled on your merchant profile:
  // paymentMethods: ['card', 'applePay', 'googlePay'],
});

---

Step 5: Handle lifecycle events#

Subscribe to events using ozow.on(eventName, handler) and unsubscribe using ozow.off.

Event catalogue

authorizationResult is not the confirmation.

The SDK reaches that outcome by polling from the browser, and it gives up after 60 seconds. It tells you what the customer's browser saw, which is not the same as what the bank did, and a customer who closes the tab produces no event at all.

The payment is confirmed the same way every other Ozow payinPayin A payment made by a consumer to a merchant. The direction most of this site is about: money coming in. Its counterpart is a payout, which sends money out and is not tied to any payment anyone made you. is: by the notification Ozow sends to your server. Because this guide creates the payment with POST /postpaymentrequest, that is the Payments API transaction notification, posted to the NotifyUrl on the request and verified by its Hash. Handle it exactly as Step 4: Handle the notification response describes: same format, same hash check.

Recommended event handler pattern

ozow.on("walletSheetOpened", () => {
  lockCartAmount();
});

ozow.on("walletTokenIssued", () => {
  showProcessingOverlay();
});

ozow.on("authorizationResult", ({ status, transactionId, reason }) => {
  hideProcessingOverlay();
  switch (status) {
    case "approved":
      return completeOrder(transactionId);
    case "cancelled":
      return unlockCheckout();
    default:
      return showPaymentFailed(reason);
  }
});

ozow.on("error", ({ error }) => {
  hideProcessingOverlay();
  showPaymentFailed(error.message);
});

---

Step 6: Handle retries and cleanup#

Call destroy() whenever the customer leaves checkout or retries a failed payment. Always create a new payment request server-side before reinitialising the SDK with a new requestId.

// Tear down listeners, iframe, and in-flight work
ozow.destroy();

// For a retry - create a new payment request server-side first
const retry = Ozow.init({
  requestId: newRequestId,
  apiBaseUrl: "https://pay.ozow.com",
  iframeBaseUrl: "https://pay.ozow.com",
});
retry.mount("#ozow-payment", { wallets: ["applePay", "googlePay"] });

---

Apple Pay setup#

Apple Pay in the Wallet SDK validates your top-level checkout domain, not the Ozow iframe origin. Ozow handles certificates and server-side merchant validation. You are responsible for domain verification.

What you must do

Cross-browser behaviour

Common Apple Pay failures

---

Google Pay setup#

No Google-side merchant onboarding is required per checkout domain. Google validates the Ozow iframe origin (pay.ozow.com), which is already approved by Google.

You only need to:

• Enable Google Pay on your Ozow merchant profile
• Ensure your CSP allows the Ozow iframe origin (see Security and CSP below)

---

Card payments#

When card is enabled on your merchant profile, the Wallet SDK can show a card payment form alongside wallet buttons. Card fields render only inside the Ozow iframe; card data never enters your DOM, keeping your checkout page out of PCI cardholder data scope. 3DS is handled entirely inside the Ozow iframe.

To include card, pass it in paymentMethods when mounting:

ozow.mount("#ozow-payment", {
  paymentMethods: ["card", "applePay", "googlePay"],
});

---

Security and CSP#

Add these directives to your checkout page Content Security Policy:

Content-Security-Policy: script-src 'self' https://cdn.ozow.com https://applepay.cdn-apple.com; frame-src 'self' https://pay.ozow.com;

Adjust the hostnames for staging (stagingpay.ozow.com).

---

Error codes#

---

Go-live checklist#

Use this checklist before going live.

Backend

• Payment request creation is server-side only, private key never in browser code
• Checkout page receives a valid requestId per payment attempt
• Order fulfilment is keyed on transactionId from authorizationResult

Frontend

• Pinned CDN URL with SRI hash on the script tag
• Ozow.init and mount use the correct environment URLs
• Handlers registered for ready, authorizationResult, and error
• destroy() called on checkout exit and before retry
• Cart amount locked after wallet sheet opens

Apple Pay

• Every checkout domain hosts .well-known/apple-developer-merchantid-domain-association
• Domain registered with Ozow and verified with Apple
• CSP allows applepay.cdn-apple.com
• No duplicate Apple Pay script or ApplePaySession mock on page

Security

• Checkout origin(s) registered on Ozow merchant allowlist
• CSP allows Ozow CDN and pay iframe origin(s)
• HTTPS on checkout domain

Card (if applicable)

• Card enabled on merchant profile
• paymentMethods includes 'card' when mounting

---

Next steps#

• Review the Building a secure integration checklist before going live
• Contact support@ozow.com to enable wallet and card payment methods on your merchant profile
• Contact Ozow to obtain the current SDK version and SRI hash for your environment
• See the Payments API reference for the full technical specification