Server to server payment notification (payment notification webhook)

Background

ShopBack Pay provides a webhook notification to inform the merchant about the status of a payment event. This webhook is triggered immediately after the payment is confirmed by ShopBack Pay.

A webhook enables ShopBack Pay to push real-time notifications to your server. ShopBack Pay uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

ShopBack webhook payload

Request Type	Content Type	Contents	Description
POST	application/json	order_status	String order_status = SUCCESS or order_status = ERROR
		order_uuid	String The unique identification of order, also received as a response when calling initiate order endpoint. You may use this variable as a cross check to the previously initiated orders
		order_context_token	String The token used to identify orders during ShopBack Pay Checkout Flow, also received as a response when calling initiate order endpoint
		cart_id	String The cart id as submitted upon merchant calling initiate order endpoint
		webhook_url	String Only available when order_status = SUCCESS
		failure_code	String Internal failure codes. Only available when order_status = ERROR

Sample responses

SUCCESS ERROR (ORDER_NOT_SUBMITTED) ERROR (HOOLAHJS_CLOSED)

Description

Transaction is successful.

Description

Order not submitted - Failed to charge the customer.

Description

Order timed out - No action from the user/ User did not complete the transaction/ User closes the app.

Steps to receive webhook

Create a webhook endpoint as an HTTP endpoint (URL) on your local server.
Add your API resource URL to the order/initiate API payload as callbackUrl.
*Example:

Handle requests from ShopBack Pay by parsing the response payload and returning 200 response status codes.

🚧
In order for the notification webhook to work reliably, merchant is advised to:

Ensure that the URL set in callbackUrl parameter is always accessible.

Ensure that the URL will respond with HTTP Status Code 200. (A failure would cause a number of retries over 30 minutes, however, there would be negative implications on the consumer experience if the order is only getting confirmed after 30 minutes)

For merchants who need to whitelist our IP address to receive callback, please whitelist the following IP addresses:

52.77.77.186
18.139.142.64
54.169.195.114
52.77.135.75
18.140.220.149
13.228.6.43
54.254.76.7

Secure your webhook (recommended)

We strongly encourage you to implement the following checks to ensure the authenticity of a callback in order to make sure that nobody else is sending you a callback with the intention of committing fraud.

Use order_uuid as signature to do a cross-reference
- When initiating an order with /order/initiate endpoint, you will be provided with the following values in the response.
- While order_context_token is a public value (used for the redirect), order_uuid is unique and only known by the merchant.
- In this case, we recommend you to compare the order_uuid you received from the payload with the expected order_uuid to increase security.

{
  "cart_id" : "34b5ds36-b24d-ds34-ds31-ds45dd563124",
  "order_context_token": "d88fd4aa-2556-11eb-adc1-0242ac120002",
  "order_status": "SUCCESS",
  "order_uuid": "a5fd004a-2555-11eb-adc1-0242ac120002"
}