Hosted Page API - Sample Requests

Ready-to-run requests for POST /v1/api/mozarto/checkout/session.

Before you start

Variable	Where it comes from
`BRAND_TOKEN`	Admin Center - API Credentials - brand `Token` (unlock the page with your 2FA code). Use a brand token, not a company token
`USER_TOKEN`	A JWT carrying the user token payload. See Authentication for how to create it

If you already use the Redirect API, your existing brand token and user token work here too. No new credentials are needed.

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

The back office must also have an active Payment Page for the session country and a matching Payments Module account. See Payment Providers.

For details on both tokens, see Authentication.

Create a session

Offers every method configured for the brand in the United Kingdom.

Without return URLs

returnUrls is optional. Without it, Close on the result screen closes the window or returns the browser to the previous page.

From your server (Node.js)

Signs the user token, creates the session, and redirects the shopper. Runs on Node.js 18 or later with express and jsonwebtoken. Never call this endpoint from the browser - it exposes your brand token.

merchantReference comes back in the webhook, so you can match the payment to the order on your server. Put the order reference in your return URLs too - Mozarto opens them exactly as sent. To embed the page instead of redirecting, see Display the page.

User token payload

Sign this payload with your Secret key and send it as x-user-token. userId and email are required. firstName and lastName are required for card payments.

{
  "userId": "user_123",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Responses

200 - session created

{
  "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"
  }
}

Send the shopper to data.checkoutUrl within 30 minutes. The session allows one payment attempt - create a new session for every retry.

400 - country missing

{
  "status": "error",
  "message": "country is required to resolve the payment configuration",
  "isSuccess": false
}

400 - amount sent as a string

Request: "baseamount": "55"

{
  "status": "error",
  "message": "amount is incorrect",
  "isSuccess": false
}

400 - return URL is not https

Request: "returnUrls": { "success": "http://shop.example.com/result" }

{
  "status": "error",
  "message": "returnUrls.success must be an https URL (http only for localhost)",
  "isSuccess": false
}

400 - no Payment Page for the country

{
  "status": "error",
  "message": "No active payment page is configured for this brand and country",
  "isSuccess": false
}

400 - no provider account for the country and currency

{
  "status": "error",
  "message": "PSP Configuration not found. Please check you psp Configuration",
  "isSuccess": false
}

401 - missing user token

Plain-text body:

External user auth token is missing!

401 - invalid brand token

Plain-text body:

Invalid Token, authorization denied

403 - company token used

{
  "status": "error",
  "message": "Checkout sessions require a brand API key",
  "isSuccess": false
}

404 - Hosted page API not enabled

{
  "error": {
    "message": "Not Found",
    "status": 404
  }
}

Contact Mozarto to enable the Hosted page API in that environment.

For every error message, see Errors.

Next steps

Display the page - redirect or iframe, and browser events.

Payment outcome - result strings and return URL mapping.

Webhook Setup - confirm the payment on your server before fulfilling the order.

Overview

Hosted Page API - Sample Requests#

Before you start#

Create a session#

Without return URLs#

From your server (Node.js)#

User token payload#

Responses#

200 - session created#

400 - country missing#

400 - amount sent as a string#

400 - return URL is not https#

400 - no Payment Page for the country#

400 - no provider account for the country and currency#

401 - missing user token#

401 - invalid brand token#

403 - company token used#

404 - Hosted page API not enabled#

Next steps#