ShopBack Notification API

openapi: 3.2.0
info:
  title: In-Store Payments Notification API
  version: '1.4'
servers:
- url: https://integrations-sandbox.shopback.com
  description: Sandbox
tags:
- name: Notification
paths:
  /<webhookUrl>:
    post:
      tags:
      - Notification
      operationId: Notification
      summary: Acknowledge notification
      description: 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.
      parameters:
      - name: Authorization
        in: header
        description: 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.
        required: true
        schema:
          example: SB1-HMAC-SHA256 <accessKeyId>:<hmacSignature>
          type: string
      - name: Date
        in: header
        description: 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
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationWebhookReqDto'
      responses:
        '200':
          description: ShopBack will record non-200 cases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationWebhookResDto'
      x-source-doc: https://docs.shopback.com/reference/notification-1
components:
  schemas:
    NotificationWebhookResDto:
      type: object
      properties:
        referenceId:
          type: string
          description: (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: 352c530dd7f747161a5e6c990c720bec
      required:
      - referenceId
    NotificationWebhookReqDto:
      type: object
      properties:
        traceId:
          type: string
          description: A unique identifier for this API request. This will be used for reconciliation as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
        shopbackOrderId:
          type: string
          description: 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.
          example: 220801-0679-YVUY
        status:
          type: string
          description: "Order status provided by ShopBack.\n\n| Status     | Description                                                                                                                                                               |\n| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| CREATED    | Order has been created.                                                                                                                                                   |\n| 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. |\n| 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.                   |\n| CANCELLED  | The order was cancelled before the customer swiped to pay.                                                                                                                |\n| CAPTURED   | ShopBack has approved the payment and it has been successful.                                                                                                             |\n| 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).                |\n| REFUNDED   | Order has been refunded in full (refund amount equal to order amount).                                                                                                    |\n      "
          enum:
          - CREATED
          - PENDING
          - PROCESSING
          - CANCELLED
          - CAPTURED
          - FAILED
          - REFUNDED
          - ABANDONED
          example: CAPTURED
        createdAt:
          format: date-time
          type: string
          description: The timestamp of the order creation time, according to <a href=https://en.wikipedia.org/wiki/ISO_8601 target="_blank">ISO-8601</a> format.
          example: '2022-08-01T02:29:33.123Z'
        updatedAt:
          format: date-time
          type: string
          description: 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.
          example: '2022-08-01T02:29:33.123Z'
        orderAmount:
          type: number
          description: The original authorised amount of the order.
          example: 1000
        refundAmount:
          type: number
          description: 'Total refunded amount for order, only provided if there has been a successful refund. '
          example: 1000
        failureReason:
          type: string
          description: Reason for order failure, only provided if an order failed.
          example: 352c530dd7f747161a5e6c990c720bec
        referenceId:
          type: string
          description: A unique order identifier generated by the POS terminal.
          example: 352c530dd7f747161a5e6c990c720bec
        currency:
          type: string
          description: 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.
          example: SGD
        posId:
          type: string
          description: Unique Id for the POS terminal given during onboarding.
          example: 802c987em7f747269a5e6c260c630kpl
        paymentType:
          type: string
          description: 'Customer’s payment type. Populated for completed and refunded orders only.

            `PAYLATER` `PAY`'
          example: PAY
      required:
      - traceId
      - shopbackOrderId
      - status
      - createdAt
      - updatedAt
      - orderAmount
      - refundAmount
      - currency
      - posId
      - paymentType
x-apievangelist-assembly:
  method: searched
  note: Assembled verbatim from the per-operation OpenAPI definitions ShopBack publishes on each API reference page of docs.shopback.com (ReadMe .md export). No content was authored or altered; path items, schemas and security schemes are exactly as published.
  fetched: '2026-08-02'
  index: https://docs.shopback.com/llms.txt
  sources:
  - https://docs.shopback.com/reference/cancel-order.md
  - https://docs.shopback.com/reference/create-dynamic-qr-order.md
  - https://docs.shopback.com/reference/get-order-status.md
  - https://docs.shopback.com/reference/notification-1.md
  - https://docs.shopback.com/reference/order-refund.md
  - https://docs.shopback.com/reference/scan-consumer-qr.md
  http_status: 200