MultiSafepay offers the possibility to subscribe to event notifications. This allows your system to receive real-time updates on order statuses without the need for manual checks.

How it works

MultiSafepay's cloud mode uses WebSockets to establish a persistent connection with our backend. Once you subscribe to our event notifications, after initiating a payment, we deliver real-time order status updates to your terminal. This ensures updates are received as soon as they occur.

This diagram shows the end-to-end flow of event notifications.

Once you have subscribed to event notifications, you will receive order payment updates when:

A customer completes the payment.
A payment is reversed.
The payment has been cancelled or declined.

Prerequisites

SmartPOS terminal must be activated in your MultiSafepay account.
Payments must be initiated via cloud POS payment.

In other scenarios, you can make use of our webhook notifications.

⚠️Note: When making requests locally, you might encounter CORS (Cross-Origin Resource Sharing) errors. We recommend using a backend proxy to handle the API requests, bypassing browser CORS restrictions.

User guide

Follow the steps below to learn how to subscribe to our event notifications.

1. Initiate a Cloud POS payment

Create an order, and setterminal_id in your request. See Recipe - Cloud POS payment .
In response, you receive an events_token and an event_stream_url.

Example request

curl --location --request POST \
'https://api.multisafepay.com/v1/json/orders?api_key={terminal_group_api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "type": "redirect",
    "order_id": "example_order_id",
    "gateway": "",
    "currency": "EUR",
    "amount": 1,
    "description": "example description",
    "payment_options": {
        "notification_url": "https://example.webhook.com"
    },
    "gateway_info": {
        "terminal_id": "00000ABC"
    }
}'

Example response

{
    "success": true,
    "data": {
        "order_id": "example_order_id",
        "session_id": "d5MrwfDyPY36t8XAb2aMh5s6nH1XHOwqrOA00Ei",
        "payment_url": "https://payv2.multisafepay.com/connect/d5MrwfDyPY36t8XAb2aMh5s6nH1XHOwqrOA00Ei/?					lang=nl_NL",
        "events_token": "WkYyQBSMvjg3nJ7dtneQT7jd-								BsyAwFlMHoqwL7FNbMuC0xkpkF.bVjgMzRRDezylsixMegHEnVFW:tnWrRblQeJNy8ZAv_x4QfOoRruySEQa2U3aZPmBcLWKVFYLDAHVKzP1YpaBykMA0u9xCD7ZRHBiznkb.FmpOsHtsOPU7o_A4.eFK2LvMhg9Pad6BbLC2x4SdczFT1RKLHcQwkVPfBPMEGcOfedQNr",
        "events_stream_url": "https://api.multisafepay.com/events/stream/"
    }
}

2. Subscribe to the event notifications

To subscribe to event notifications make a GET request, using the events_token and the events_stream_url from your response. See recipe - Subscribe to Event notifications

Example request

curl --location --request GET \
'https://api.multisafepay.com/events/stream/' \
--header 'Authorization: WkYyQBSMvjg3nJ7dtneQT7jd-								BsyAwFlMHoqwL7FNbMuC0xkpkF.bVjgMzRRDezylsixMegHEnVFW:tnWrRblQeJNy8ZAv_x4QfOoRruySEQa2U3aZPmBcLWKVFYLDAHVKzP1YpaBykMA0u9xCD7ZRHBiznkb.FmpOsHtsOPU7o_A4.eFK2LvMhg9Pad6BbLC2x4SdczFT1RKLHcQwkVPfBPMEGcOfedQNr'

Example response

event: session.order
data: {"financial_status":"initialized","order_id":"example_order_id","session_id":"d5MrwfDyPY36t8XAb2aMh5s6nH1XHOwqrOA00Ei","status":"initialized","transaction_id":"89000000"}
event: session.order
data: {"financial_status":"completed","order_id":"example_order_id","session_id":"d5MrwfDyPY36t8XAb2aMh5s6nH1XHOwqrOA00Ei","status":"completed","transaction_id":"890000000"}

⚠️Note: You cannot initiate another payment until the current payment is Cancelled or Completed.

Payment statuses

The table below sets out possible payment statuses and what they commonly mean.

Description	Payment status
The card scheme is processing your payment request.	Initialized
The payment has been cancelled on the terminal or via API, or has expired after 60 seconds of inactivity. For more information - see Cancellation. Note: You can now initiate another cloud POS payment.	Cancelled
The customer has completed the payment. Note: You can now initiate another cloud POS payment.	Completed
The card scheme has declined the payment. The customer will be redirected to the payment screen to retry the payment. In certain cases, a payment may be soft declined, meaning the customer must authenticate to proceed with the transaction. For more information, see Soft declines - SmartPOS solutions.	Declined

Top of page