Pay-In Flow

The Hosted page API lets your platform accept Pay-Ins through a payment page hosted by Mozarto. Your backend creates a checkout session, and the shopper completes payment on the Mozarto page, either after a redirect or inside an iframe on your site.

Unlike the Redirect API, your platform does not choose the payment provider per request. The page offers every method configured for your brand and the shopper's country. Mozarto collects the payment details, runs 3D Secure, and talks to the provider.

How it works

Create the session from your backend.

Display the page with a redirect or an iframe.

Handle the outcome in your UI, and confirm the payment from the webhook.

Session lifecycle

Rule	Behaviour
Lifetime	A session expires 30 minutes after creation. An expired session cannot be opened or paid.
Single use	The first payment attempt consumes the session. A declined or failed payment also consumes it.
Retry	Create a new session for every new attempt. Do not reuse `checkoutUrl`.
Status	A session is either `created` or `consumed`. It is not exposed to your platform.

User token requirements

Create the session with the same user context headers as the Redirect API (see Authentication). The hosted page reads the shopper's identity from that token, not from the browser.

Claim	Required	Purpose
`userId`	Yes	Links the transaction and saved cards to your shopper
`email`	Yes	Required to pay
`firstName`	Card payments	emerchantpay rejects card payments without the billing name
`lastName`	Card payments	Same as `firstName`

Missing claims fail after the session is consumed. The session is created without checking these claims. If userId or email is missing, the payment attempt fails and the session cannot be reused. Validate the token on your side before creating the session.

Mozarto decodes the token from x-user-token or x-user-authorization without calling your User Auth URL, so the token must be a JWT that carries these claims.

Saved cards

When the user token carries a userId, the shopper can tick Remember card on a card payment (unchecked by default). Saved cards appear on later sessions for the same brand, userId, and provider account. Without a userId, no cards are saved or shown.

Create the session

Create a checkout session from your backend, then send the shopper to the returned checkoutUrl.

The request carries only the payment details. Everything else - the payment methods, provider accounts, page content, and webhook URLs - comes from your back office configuration (Payment Pages and Payments Module).

Endpoint

POST /v1/api/mozarto/checkout/session

Environment	Base URL
Sandbox	`https://checkout-api.stg-app.mozarto.io`
Production	`https://checkout-api.app.mozarto.io`

Authorization: Bearer <brand-jwt>
x-user-token: Bearer <user-jwt>
Content-Type: application/json

Use a brand JWT. A company JWT returns 403 Checkout sessions require a brand API key. See Authentication and the user token requirements.

A 404 Not Found means the Hosted page API is not enabled in that environment. Contact Mozarto to enable it.

Request fields

Fields marked with * are required.

Field	Type	Description
`country` *	string	Shopper's country - ISO 3166-1 alpha-2 recommended (e.g. `"GB"`). Selects the Payment Page and provider account. See Country Codes
`baseamount` *	number	Amount in major units (e.g. `55` or `25.50`). Must be a JSON number - a string such as `"55"` is rejected
`currency` *	string	Three-letter ISO 4217 code (e.g. `"EUR"`)
`merchantReference`	string	Optional. Your own reference for the payment, such as an order ID. Stored on the transaction and returned as `merchantReference` in the webhook. Defaults to an empty string
`returnUrls`	object	Where to send the shopper when they close the page. Keys: `success`, `failure`, `cancel`, `pending`. Each must be `https` (`http` only for `localhost`). See Return URLs

Example

Response

{
  "status": "success",
  "message": "Session created",
  "isSuccess": true,
  "data": {
    "sessionToken": "9b2f6c1e-4a7d-4f0e-8c3b-2d5e1a6f7b90",
    "checkoutUrl": "https://<checkout-host>/checkout/9b2f6c1e-4a7d-4f0e-8c3b-2d5e1a6f7b90",
    "expiresAt": "2026-10-29T12:30:00.000Z"
  }
}

Field	Description
`data.sessionToken`	Session identifier. Single use
`data.checkoutUrl`	The hosted page. Redirect the shopper to it or load it in an iframe. Use the value as returned - do not build it yourself
`data.expiresAt`	ISO 8601 expiry, 30 minutes after creation

Errors

Validation errors return HTTP 400 with { "status": "error", "message": "...", "isSuccess": false } and no errorCode. See Errors for every message and its fix.

For more requests and responses, see Sample requests.

Display the page

Show the hosted page in one of two ways. The same checkoutUrl works for both - you do not configure the display mode in the request.

	Redirect	Iframe
How to open	Navigate the browser to `checkoutUrl`	Load `checkoutUrl` in an `<iframe>` on your page
Setup	None	Your page's origin must be configured for your brand
Outcome	Return URLs	Browser events
3D Secure	Runs first-party - most reliable	Runs inside the frame - can be affected by third-party cookie blocking in Safari and Firefox

Use redirect when you can. It avoids browser restrictions on embedded 3D Secure pages.

Redirect

Iframe

Requirement	Detail
Allowed origin	Your page's origin must be in the brand's allowed origins. See Allowed origins
Referrer	The page identifies your origin from the `Referer` header. Do not set `Referrer-Policy: no-referrer` on the embedding page, or browser events are not sent
Size	At least 390 x 400 CSS pixels for 3D Secure challenges, ideally 500 x 600 or larger
`sandbox`	Do not set it. If you must, include `allow-scripts allow-same-origin allow-forms allow-popups` - card and 3D Secure pages need forms and scripts
Content Security Policy	Your `frame-src` must allow the checkout origin and issuer 3D Secure pages (`https:`), or omit `frame-src`

Allowed origins

Mozarto configures the list of origins that may embed the page for your brand. Each entry is https://host (or http://localhost:port for development), with no path. Contact Mozarto to change the list.

Every session for your brand allows all origins on that list. Without a configured list, the page still loads but sends no browser events to your page - use redirect instead.

Browser events

In an iframe, the page sends postMessage events to your page. Events go only to an origin confirmed against the session's allowed origins. Always check event.origin before reading the data.

`type`	Payload	When
`MOZARTO_HPP_READY`	`sessionId`, `mode`, `supportedMethods`	The page has loaded the session
`MOZARTO_HPP_RESIZE`	`height`	The content height changed - resize the iframe
`MOZARTO_HPP_REDIRECTING`	`target` (`"iframe"` or `"top"`), `pspType`, `transactionId`	The page is navigating to a provider or 3D Secure page
`MOZARTO_HPP_FINAL_STATUS`	`transactionId`, `finalStatus`	The payment reached a result. See Payment outcome
`MOZARTO_HPP_CLOSE`	`transactionId`, `finalStatus`, `autoClose`	The shopper clicked Close. Remove the iframe

Treat browser events as UI signals. They come from the shopper's browser and are not proof of payment. See Confirming a payment.

3D Secure

3D Secure runs inside the hosted page for every method. The issuer's challenge returns to the hosted page, not to your returnUrls. Your platform does not need to handle 3D Secure redirects.

Payment outcome

The hosted page shows the result to the shopper and reports it to your page. How your page receives it depends on how you display the page:

Iframe: MOZARTO_HPP_FINAL_STATUS when the payment reaches a result, then MOZARTO_HPP_CLOSE when the shopper clicks Close.

Redirect: the shopper is sent to one of your returnUrls when they click Close.

`finalStatus` values

Match on these exact strings in MOZARTO_HPP_FINAL_STATUS and MOZARTO_HPP_CLOSE.

`finalStatus`	Meaning	Final
`Payment successful`	The payment was approved	Yes
`Payment failed`	The payment was declined or failed	Yes
`Card verification failed`	3D Secure authentication failed	Yes
`Payment is still being processed`	The provider has not confirmed the result yet	No
`Card verification incomplete`	3D Secure did not complete	No
`Session expired`	The session expired or was already used. Sent on `MOZARTO_HPP_CLOSE` only, with an empty `transactionId`	Yes

The session is consumed in every case. Create a new session to let the shopper try again.

Return URLs

When the page is not inside a confirmed iframe, Close sends the top window to one of your returnUrls:

Result	Return URL used
`Payment successful`	`success`
`Payment failed` or `Card verification failed`	`cancel`
`Payment is still being processed` or `Card verification incomplete`	`pending`
`Session expired`	`failure`

The shopper is not sent back automatically. The return URL is used only when they click Close.

Mozarto opens the URL exactly as you sent it and appends no query parameters. Put your own order reference in the URL if you need it (for example https://shop.example.com/checkout/result?order=ord_123).

If the matching URL is not set, Close closes the window (popups) or returns the browser to the previous page.

Confirming a payment

Browser events and return URLs come from the shopper's browser. Use them to update your UI, not to credit an account or ship an order.

Mozarto sends the final transaction_status to your webhook URL. Credit the account or fulfil the order only after the webhook arrives. See Webhook Setup.

How it works#

Session lifecycle#

User token requirements#

Saved cards#

Create the session#

Endpoint#

Request fields#

Example#

Response#

Errors#

Display the page#

Redirect#

Iframe#

Allowed origins#

Browser events#

3D Secure#

Payment outcome#

finalStatus values#

Return URLs#

Confirming a payment#