This guide provides implementation details and examples for each supported MultiSafepay POS payment flow.

Before integration, ensure that the terminal is connected to a stable network and has been activated from your MultiSafepay dashboard.

Manual input

Manual input allows you to process standalone transactions from the MultiSafepay payment application and does not require additional integration steps.

How to initiate a payment

To process a payment using Manual input:

Enter Amount due and select Pay.
The customer taps or inserts their card to complete the payment.
When the payment is completed, a confirmation is displayed on the device.

Payments processed with Manual input are automatically assigned an order_id.

To use a custom order_id, choose one of the following methods:

Manual order ID

You can use the Insert Order ID feature to enter a custom order_id using Manual input. To process payments where you can manually insert an Order ID:

Click Insert Order ID and insert the ID for your order.
Enter the amount you want to charge.
Click Pay to initiate the payment.

QR code payments

You can initiate a payment by scanning a QR code with the terminal. To do this, first enable the Insert Order ID feature in the MultiSafepay App.

To create a QR code:

Create a JSON object containing the following parameters:

order_id: The unique id of the order
amount: Order amount in cents
description: Order description

These parameters are required to create the order, and can be later retrieved from the MultiSafepay dashboard , or via our API, by creating a Get order request.

Check the example below for reference:

{
  "order_id":"your_order_id",
  "amount":100,
  "description":"Your order description"
}

Generate a QR code from the JSON object.
In Manual input, click Scan QR, then scan the QR code. The payment details are displayed on the screen.
Click Pay to initiate the payment.

Cloud POS payments

With cloud POS payment, you can initiate payments from an external application.

This diagram shows a successful cloud-based POS payment flow. Click to magnify.

---
config:
  theme: default
  themeVariables:
    mainBkg: "#3fa9f5"
    actorTextColor: white
    actorBorder: "#d2dae3"
    noteBkgColor: "#faebbf"
    noteBorderColor: "#faebbf"
    labelBoxBkgColor: "#f2f7fc"
    labelBoxBorderColor: "#d2dae3"
  sequence:
    messageFontFamily: "mulish extralight"
    messageFontWeight: normal
    messageFontSize: 12
    actorFontWeight: normal
    actorFontFamily: "mulish"
    actorFontSize: 16
    noteFontFamily: "mulish"
    noteFontSize: 12
---
sequenceDiagram
    participant Kiosk
    participant Merchant
    participant MultiSafepay
    participant Terminal

    Kiosk->>Merchant: Initiates an order payment
    Merchant->>MultiSafepay: Creates an order via API
    MultiSafepay->>Merchant: Returns response
    MultiSafepay->>Terminal: Initiates payment
    Merchant->>MultiSafepay: Subscribes to event notifications
    Terminal->>MultiSafepay: Authorizes payment process
    MultiSafepay->>Kiosk: Event notifications
    opt
        MultiSafepay->>Kiosk: Webhook
    end

⚠️
Note:
Cloud POS payments are not designed for on-device integrations.
Avoid using Cloud POS for applications running on the same device.
Instead, use the App-to-app or Web-to-app flows.

Integration steps

Enable cloud mode

In your MultiSafepay payment app, go to Features > Payment and enable the Cloud mode toggle. Your device switches to Cloud mode.

Return to the main screen and click Cloud Payment. The device is now ready to receive payment requests from your backend.

To receive payments requests, the device must remain powered on. Configure the display settings so that the screen does not turn off automatically.

Prepare your backend

Once Cloud mode is enabled, your backend can create payment requests using the /orders endpoint. For more information, see API Reference - Create Cloud order .

Retrieve your terminal group API key from your MultiSafepay dashboard , under Manage groups.

Include the API key as the api_key query parameter when calling the /orders endpoint.

Include the following required parameters:

https://api.multisafepay.com/v1/json/orders?api_key=TERMINAL_GROUP_API_KEY

Parameter	Description
`type`	Order type. Use `redirect`.
`order_id`	Unique identifier for the order.
`currency`	Currency used for the transaction.
`amount`	Total order amount in cents.
`description`	Description of the order.
`payment_options.notification_url`	URL that receives payment status updates.
`payment_options.notification_method`	HTTP method used for notifications. Use `POST`.
`gateway_info.terminal_id`	Terminal ID of the device that processes the payment.

💡
To find your terminal ID, access your MultiSafepay payment app, go to Features, and click About. You will find it next to TID.

Subscribe to event notifications

Optionally, subscribe to our Event notifications to receive real-time status updates. Use event notifications to keep your backend synchronized with the payment status.

Check the example in the dropdown below to see how the request is sent to our server.

Example /orders request with cloud mode

Example request

curl --request POST \
  --url 'https://api.multisafepay.com/v1/json/orders?api_key=YOUR_GROUP_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "redirect",
  "order_id": "your-order-id",
  "currency": "EUR",
  "amount": 100,
  "description": "Order description",
  "payment_options": {
    "notification_url": "https://www.example.com/event-notifications",
    "notification_method": "POST"
  },
  "gateway_info": {
    "terminal_id": "your-terminal-id"
  }
}'

Example response

{
  "success": true,
  "data": {
    "order_id": "your-order-id",
    "payment_url": "https://pay.multisafepay.com/your-payment-url",
    "session_id": "your-session-id",
    "events_token": "your-events-token",
    "events_stream_url": "https://api.multisafepay.com/events/stream/"
  }
}

How to initiate a payment

After integrating Cloud POS payments into your system, you can process your first payment. Make sure you have correctly integrated Cloud POS payments.

To complete a Cloud POS payment:

Create an order

Make a request to our API with the /orders endpoint and include the correct terminal group API key for authentication along with the relevant terminal_id.

Process the payment request

After the order is created successfully, the payment request is forwarded to the specified terminal, which displays the payment screen.

Complete the payment

The customer can then complete the payment using a supported payment method.

Web applications

Web applications allow you to initiate payments from a browser to the MultiSafepay payment app on the same device.

This diagram shows a successful web application payment flow. Click to magnify.

---
config:
  theme: default
  themeVariables:
    mainBkg: "#3fa9f5"
    actorTextColor: white
    actorBorder: "#d2dae3"
    noteBkgColor: "#faebbf"
    noteBorderColor: "#faebbf"
    labelBoxBkgColor: "#f2f7fc"
    labelBoxBorderColor: "#d2dae3"
  sequence:
    messageFontFamily: "mulish extralight"
    messageFontWeight: normal
    messageFontSize: 12
    actorFontWeight: normal
    actorFontFamily: "mulish"
    actorFontSize: 16
    noteFontFamily: "mulish"
    noteFontSize: 12
---
sequenceDiagram
    participant Web applications
    participant Terminal

    Web applications->>Terminal: Initiates payment
    Terminal->>Web applications: Returns payment status via callback
    opt
        Terminal->>Web applications: Webhook
    end

Integration steps

Prepare your backend

The Web-to-app payment flow launches the MultiSafepay payment app from your web application using a deep link. After the payment is completed, the customer is redirected back to your application through the callback URL.

Use the following URL to initiate a payment:

msp://?amount=amount&order_id=order_id&callback=callback_url&notification_url=notification_url

Include the required parameters:

Parameter	Description
`amount`	Total order amount in cents.
`order_id`	Unique identifier for the order.
`callback_url`	URL to which the customer is redirected after the payment.
`notification_url`	Optional URL that receives asynchronous payment status updates.

How to initiate a payment

After completing the integration, you can initiate payments from your web application.

Launch the payment app

Create an order from your web app and use the MultiSafepay URL scheme to launch the payment app and pass the payment details.

Complete the payment

Once the order is created, the user is redirected from your web app to the MultiSafepay payment app. The customer can then complete the payment using a supported payment method.

Native applications

Native applications let you initiate payments from your app to the MultiSafepay payment app on the same device.

This diagram shows a successful native application payment flow. Click to magnify.

---
config:
  theme: default
  themeVariables:
    mainBkg: "#3fa9f5"
    actorTextColor: white
    actorBorder: "#d2dae3"
    noteBkgColor: "#faebbf"
    noteBorderColor: "#faebbf"
    labelBoxBkgColor: "#f2f7fc"
    labelBoxBorderColor: "#d2dae3"
  sequence:
    messageFontFamily: "mulish extralight"
    messageFontWeight: normal
    messageFontSize: 12
    actorFontWeight: normal
    actorFontFamily: "mulish"
    actorFontSize: 16
    noteFontFamily: "mulish"
    noteFontSize: 12
---
sequenceDiagram
    participant Native applications
    participant Terminal

    Native applications->>Terminal: Initiates payment via intent call
    Terminal->>Native applications: Returns payment status via callback
    opt
        Terminal->>Native applications: Webhook
    end

Integration steps

Prepare your backend

Native app integrations use Android Intents to launch the MultiSafepay payment app from your application.

Your application launches the MultiSafepay payment app using an Android Intent and passes the payment details. After the payment is completed, the customer is redirected back to your application through the callback defined in the Intent.

See the integration guide:
MultiSafepay Android POS integration

How to initiate a payment

After completing the integration, you can initiate payments from your native application.

Launch the payment app

Build the payment request and launch the MultiSafepay payment app using an Android Intent. The Intent contains the payment details required to start the transaction.

Complete the payment

The MultiSafepay payment app opens and displays the payment amount. The customer completes the payment using a supported payment method.

Handle redirection

After the payment is completed, the payment app redirects the customer back to your application.

Next step

User guide

Learn how to issue refunds, cancel transactions, and use the available device features.