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 configured in the Mozarto back office under Payment Methods - Configuration for your company (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.

An Orchestration rule created for your company and the chosen PSP under Orchestration. Without an active rule, all transaction requests are rejected with "Rules action is not matched".

An HTTPS endpoint on your platform to receive webhook callbacks

Step 1 - Authenticate

Every request requires your company 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#