Quick Start

Get a Pay-In integration running in five steps. The same steps apply to every provider - only the request body fields differ.

Prerequisites

A Mozarto account with API credentials

A payment provider account configured in the Mozarto back office under Payments Module for your brand (username, password, webhook URL, and any provider-specific fields) - see Back office configuration. Requests will return "PSP Configuration not found" if this step is skipped.

A Processing Scope on that account covering the country and currency you send. Requests that fall outside the configured scope are rejected.

A country on every request. It is what the Processing Scope is matched against - if you omit it, Mozarto geo-locates the caller's IP, which reports your server's country rather than the payer's. See Country.

An HTTPS endpoint on your platform to receive webhook callbacks

Step 1 - Authenticate

Every request requires your brand JWT in the Authorization header.

See Authentication for how to generate your JWT.

Step 2 - Initiate a Pay-In

When your user clicks "Pay-In", call the Cashier endpoint with pspType set to your chosen provider:

Response:

{
  "status": "success",
  "isSuccess": true,
  "data": {
    "status": "PENDING",
    "transactionId": "64a1f2b3c4d5e6f7a8b9c0d1"
  }
}

Note: The redirect URL field name in data varies by provider - for example, data.url, data.paymentUrl, data.redirect_url, or data.webflowURL. Check the relevant PSP page for the exact field name before implementing redirect logic.

For the full request and response reference for each flow, see:

Pay-In Flow - Pay-In request fields, redirect handling, and webhook lifecycle

Pay-Out Flow - Pay-Out request fields, approval flow, and webhook lifecycle

Step 3 - Redirect the user

Open the redirect URL from the response data object in the user's browser. Set a pending state before redirecting - the final outcome does not arrive on return from the PSP page, it arrives via webhook.

For the full implementation including the UI state machine and redirect URL handling, see Pay-In Flow.

Step 4 - Receive the webhook

When the payment is confirmed or cancelled, Mozarto calls your configured webhookUrl:

{
  "transaction_id": "64a1f2b3c4d5e6f7a8b9c0d1",
  "psp_transaction_id": "HS923856HU",
  "user_id": "user_123",
  "status": "confirmed",
  "transaction_status": "Approved",
  "message": "Payment confirmed",
  "amount": "50.00",
  "currency": "EUR",
  "merchantReference": ""
}

Respond with HTTP 200 to acknowledge receipt.

Step 5 - Update your system

Use transaction_status to update the user's balance or order status. The status field is a raw PSP value and varies by provider - do not use it for business logic.

Statuses are either Middle (intermediate - transaction is still in progress) or Final (no further changes will occur). Only apply balance or order changes on a Final status.

`transaction_status`	Pay-in	Payout	Type	Meaning	Action
`Initiated`	yes	yes	Middle	Transaction successfully initiated, in authentication stage	Show pending state - do not update balance
`Pending`	yes	no	Middle	Transaction passed authentication and sent to PSP, waiting for callback	Show pending state - do not update balance
`On Hold`	no	yes	Middle	Payout submitted by merchant, awaiting Mozarto processing	Show "pending approval" message - do not update balance
`Processing`	no	yes	Middle	Payout approved for processing by Mozarto	Show "processing" message - do not update balance
`Approved`	yes	yes	Final	Transaction completed successfully	Credit or debit the user
`Declined`	yes	yes	Final	Transaction declined by PSP	Notify the user, allow retry
`Failed`	yes	yes	Final	Transaction failed due to a technical error in Mozarto, PSP, or authentication	Notify the user, allow retry
`Rejected`	no	yes	Final	Payout rejected by Mozarto or merchant	Notify the user

Next steps

Authentication - token details and expiry

The Redirect Flow - full flow with all edge cases

Webhook Setup - payload reference, security, duplicate handling

PSP pages - request fields for each provider

2. Quick Start

Quick Start#

Prerequisites#

Step 1 - Authenticate#

Step 2 - Initiate a Pay-In#

Step 3 - Redirect the user#

Step 4 - Receive the webhook#

Step 5 - Update your system#

Next steps#