Skip to content

Merchant Notification Service

Subscribe to merchant notifications to updated about events on transactions. Version 3 notifications are sent in JSON format.

When to use Merchant Notifications

The Worldline Merchant Notification Service (MNS) is a callback service of Worldline to deliver v3 notification to the merchants. It provides the merchant with a notification when there is a change in an order state. For example, any transaction or order event that changes the order status or changes the order amounts. In order to support the evolving API's, v3 notification has been implemented which sends JSON response to the merchants through REST service. The notification v3 has a JSON body for a Query Order Response.

Receiving Merchant Notifications

Workflow

Workflow

To successfully receive notifications, the merchant needs to set up an HTTPS service that listens to HTTP POST calls. The HTTP body will contain a JSON object with updates on one or several events. The HTTP header or JSON object may contain additional elements that the merchant needs to gracefully ignore, if not recognized.

When a notification is received, use the Worldline API to get the details on the order and transactions.

Notification v3 Protocol

The Merchant Notification Service of Worldline sends a v3 notification (in JSON format) to the merchant through a REST service via HTTPS port. To receive v3 notification, the merchant must be configured with a REST endpoint and a HTTPS port both in the acceptance and in the production environments. The merchant queries the Worldline API with the merchantId and Order ID. The orderId is URL encoded in the links provided to the merchant. Before querying back, the merchant needs to decode the orderId.

If the merchant's notification receiver is down or unreachable, the Worldline Merchant Notification Service will retry to send the notification for few days before it is removed.

Note: The Merchant Notification Service for v3 supports Content-Type application/json, charset UTF-8, in the response from the Merchants web service back to Worldline web client.

Elements of Notification v3

Notification v3 has the following fields with corresponding datatypes:

  • merchantId (String)
  • orderId (String)
  • transactionId (String)
  • links (List <String> <String>)
Element Description
merchantId The unique Worldline merchant identification number.
orderId A unique identifier of the order set by the merchant. The same OrderId that was used in transaction which refers to that particular order.
transactionId Worldline assigned transactionID. This can be used in QueryOrder calls to retrieve transaction details.
links They are used to query back to Worldline. It consists of rel and href.

Receiving Merchant Notifications

Worldline will validate that the Merchant endpoint certificate is secure before sending the notification. In order to be seen as secure, the server must be correctly configured to support HTTPS with a valid certificate.

Sample Notification v3

Notification v3 from Worldline to the Merchant

REST API
{ 
    "mid": "1211853605", 
    "orderId": "ORDER1537441138",   
    "transactionId": "10011537441138", 
    "notificationTimestampEpoch": 1537441393820, 
    "links": [
        { 
            "rel": "self", 
            "href":"/v1/merchants/1211853605/orders/ORDER%23F1537441138" 
        }
    ] 
}

Responding to a Merchant Notification

When receiving a notification, the merchant system must respond with HTTP status 201. All other responses, or if the merchant server does not respond at all or is unavailable, then Worldline will treat the notification as not received.

Back to top