v1

latestOpenAPI 3.0.12026-07-24204977.5 KB

Notification

Acknowledge notification

This API is implemented by the payment partner. ShopBack will send the following request parameters to the webhookUrl supplied by the payment partner during onboarding.

post/<webhookUrl>

Headers

Authorizationstring required

Example:SB1-HMAC-SHA256 <accessKeyId>:<hmacSignature>

Header provided for authorization. This is provided for optional HMAC verification when ShopBack calls the webhookUrl. Please refer to Generating an HMAC Signature for a step by step guide to generating the Authorization signature.

Datestring required

Example:2022-08-22T02:29:33.123Z

The date and time of request in <a href=https://en.wikipedia.org/wiki/ISO_8601 target="_blank">ISO-8601</a> format. This is the same value used in the generation of the HMAC signature

Request body

traceIdstring required

A unique identifier for this API request. This will be used for reconciliation as necessary.

shopbackOrderIdstring required

This is a unique ID generated by ShopBack, returned when the order status has reached either CAPTURED or FAILED from PROCESSING. This ID is displayed on the consumer ShopBack mobile app. Keeping track of this ShopBack Order ID on POS terminal displays can help with in-store refunds. This will also be displayed on ShopBack’s Merchant Portal.

Order status provided by ShopBack.

Status	Description
CREATED	Order has been created.
PENDING	The payment is pending action from the customer. This indicates that the customer has scanned the QR code on ShopBack’s mobile application but has not yet swiped to pay.
PROCESSING	The payment is being processed. This indicates that the customer has swiped to pay on ShopBack’s mobile application and the payment is being completed.
CANCELLED	The order was cancelled before the customer swiped to pay.
CAPTURED	ShopBack has approved the payment and it has been successful.
FAILED	ShopBack has declined the payment (there could be a number of reasons including the customer’s underlying payment method not having a sufficient balance).
REFUNDED	Order has been refunded in full (refund amount equal to order amount).

createdAtstring date-time required

The timestamp of the order creation time, according to <a href=https://en.wikipedia.org/wiki/ISO_8601 target="_blank">ISO-8601</a> format.

updatedAtstring date-time required

The timestamp of the order’s latest update, according to <a href=https://en.wikipedia.org/wiki/ISO_8601 target="_blank">ISO-8601</a> format.

orderAmountnumber required

The original authorised amount of the order.

refundAmountnumber required

Total refunded amount for order, only provided if there has been a successful refund.

failureReasonstring

Reason for order failure, only provided if an order failed.

referenceIdstring

A unique order identifier generated by the POS terminal.

currencystring required

Currency that is associated with the payment amount. Specify the three-letter ISO currency code following <a href=https://en.wikipedia.org/wiki/ISO_4217 target="_blank">ISO-4217</a> standard.

posIdstring required

Unique Id for the POS terminal given during onboarding.

paymentTypestring required

Customer’s payment type. Populated for completed and refunded orders only. PAYLATER PAY

Example request

{
  "traceId": "0dc44317-1c4b-4b62-83a8-8997435511e4",
  "shopbackOrderId": "220801-0679-YVUY",
  "status": "CAPTURED",
  "createdAt": "2022-08-01T02:29:33.123Z",
  "updatedAt": "2022-08-01T02:29:33.123Z",
  "orderAmount": 1000,
  "refundAmount": 1000,
  "failureReason": "352c530dd7f747161a5e6c990c720bec",
  "referenceId": "352c530dd7f747161a5e6c990c720bec",
  "currency": "SGD",
  "posId": "802c987em7f747269a5e6c260c630kpl",
  "paymentType": "PAY"
}

Response

ShopBack will record non-200 cases.

referenceIdstring required

(Required only for static QR orders) A unique order identifier generated by the POS terminal. If the referenceId has not been previously supplied, this response referenceId will be recorded in the ShopBack order that was created through a static QR flow.

Example response

{
  "referenceId": "352c530dd7f747161a5e6c990c720bec"
}