# Embed checkout in your own page

> Everything needed to keep the customer on your site while they pay, as an iframe, a modal, or the Wallet SDK for Apple Pay and Google Pay, with the notification that actually confirms the payment.

Three ways to take a payment without sending the customer to a page of Ozow's:
the payment page in an iframe on your checkout, the same page in a modal over
it, or the Wallet SDK rendering Apple Pay, Google Pay and optionally card into a
container you place. They are alternatives, not steps. Read the comparison, then
implement one.

**All three are on the Payments API, not One API.** Authentication and the
notification are the Payments API's throughout: an API key and a hash, not a
bearer token and a Svix signature. Create the payment request server-side with
`POST /postpaymentrequest`, which returns `paymentRequestId`; the SDK takes that
value as its `requestId` option. For a redirect payin, take `take-a-payment`
instead. Mixing the two contracts in one integration means two sets of
credentials and two notification formats.

**The SDK's events are not confirmation.** The outcome arrives as a notification
to your `NotifyUrl`, hash verified. A `postMessage` event or a redirect to your
success URL reports what the browser did, not what the bank did.

The hash is computed from your private key, so the payment request must be built
server-side in every case. Browser code that builds it has published the key.

## What this was built from

- Ozow Hub, commit `e0b2a572`
- `payments-api` version 1.0, OpenAPI document: https://hub.ozow.com/api-reference/specs/payments-api.yaml
- Build against `https://api.ozow.com` for `payments-api`
- 9 pages, 3 operations
- Everything below inlined in one document: https://hub.ozow.com/bundles/embed-checkout-in-your-page-full.md

## Implement against these

Every field name, order and format on these pages is exact.

- [Embedded iframe](https://hub.ozow.com/integration-methods/apis/payin/embedded-iframe.md): Load the Ozow payment page inside a container on your own checkout with the Ozow SDK, so your customer never leaves your site.
- [Embedded modal](https://hub.ozow.com/integration-methods/apis/payin/embedded-modal.md): Open the Ozow payment page as an overlay on your own checkout with the Ozow SDK, so your customer pays without leaving the page.
- [Embedded wallet](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md): Offer Apple Pay, Google Pay and cards on your own checkout through a secure Ozow iframe, so card data never touches your page. Approved merchants only.
- [Payin test cases](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/payin-test-cases-payments-api.md): The payments to run before you go live on the Payments API, what each one delivers, and a notification handler that survives all of them.

## Background

Context for the above. Nothing here is implemented against.

- [How Ozow works](https://hub.ozow.com/getting-started.md): How Ozow connects you to South African banks and payment methods, and the two directions money moves: payins from customers, payouts to recipients.
- [Prerequisites and onboarding](https://hub.ozow.com/getting-started/prerequisites-and-onboarding.md): What to have in place before you write any code: a merchant account, Dashboard access, your credentials, and payout eligibility if you need it.
- [Choosing a checkout experience](https://hub.ozow.com/integration-methods/apis/payin.md): Where your customer pays decides how much you build and whether you take on PCI DSS scope. Compare redirect, embedded and server to server.
- [Hash calculator](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/hash-calculator.md): Work out the hashCheck a request carries, and see the exact string it is computed from.
- [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md): Where Ozow's security responsibility ends and yours begins: credentials, webhook endpoints, verifying notifications, and validating amounts.

## The contract

Fetch the OpenAPI document named above to generate a client, or to check a field name or an enum against the schema.

- [payments-api#get-/GetTransactionByReference](https://hub.ozow.com/api-reference/payments-api/get-get-transaction-by-reference.md)
- [payments-api#post-/postpaymentrequest](https://hub.ozow.com/api-reference/payments-api/post-post-payment-request.md)
- [payments-api#webhook/transactionNotification](https://hub.ozow.com/api-reference/payments-api/webhooks/transaction-notification.md)