openapi: 3.0.1
info:
  title: In-Store Payments API
  version: '1.4'
servers:
- url: https://integrations-sandbox.shopback.com
  description: Sandbox
tags:
- name: Orders
paths:
  /posi-sandbox/v1/instore/order/{referenceId}/cancel:
    post:
      tags:
      - Orders
      operationId: Cancel order
      summary: Cancel order
      description: Use this endpoint to cancel a payment before processing. Cancellations are not allowed
        once a customer has swiped-to-pay on ShopBack’s mobile application.
      parameters:
      - name: referenceId
        required: true
        in: path
        description: The unique payment attempt identifier generated by the POS terminal that was sent
          in the request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Header required for authorization. Specify the HMAC signature in the Authorization
          header along with `accessKeyId`.

          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 should be the same value used in the generation of the HMAC signature
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      - name: X-ShopBack-Idempotent-Id
        in: header
        description: Idempotent Id for the request. If this is absent,  every request will be treated
          as unique and will be processed as such. (This is optional for now, but will be made required
          in the future)
        schema:
          example: faa5e09a-8cf3-43f7-8309-d94deb426e66
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCancelOrderReqDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResDto'
        '400':
          description: ''
          content: {}
        '401':
          description: ''
          content: {}
        '404':
          description: ''
          content: {}
        '409':
          description: ''
          content: {}
      x-source-doc: https://docs.shopback.com/reference/cancel-order
  /posi-sandbox/v1/instore/order/create:
    post:
      tags:
      - Orders
      operationId: Create dynamic QR order
      summary: Create order - QR / URL (dynamic)
      description: Use this endpoint to create an order to accept payment using ShopBack’s dynamic QR
        code or to accept payments for an in-store context through a customer-facing app or website. This
        endpoint creates a payment order with the dynamic QR code or relevant URL for redirect.
      parameters:
      - name: Authorization
        in: header
        description: 'Header required for authorization. Specify the HMAC signature in the Authorization
          header along with `accessKeyId`.

          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 should be the same value used in the generation of the HMAC signature
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      - name: X-ShopBack-Idempotent-Id
        in: header
        description: Idempotent Id for the request. If this is absent,  every request will be treated
          as unique and will be processed as such. (This is optional for now, but will be made required
          in the future)
        schema:
          example: faa5e09a-8cf3-43f7-8309-d94deb426e66
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCreateOrderReqDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResDto'
        '400':
          description: API Request could not be processed. This could be due to validation errors or invalid
            inputs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadReqDto'
        '401':
          description: Invalid signature. Failed to match HMAC signatures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDto'
        '404':
          description: Target resource(s) not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResDto'
        '409':
          description: Invalid ReferenceId. ReferenceId provided is already assigned to an existing resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResouceConflictDto'
      x-source-doc: https://docs.shopback.com/reference/create-dynamic-qr-order
  /posi-sandbox/v1/instore/order/{referenceId}:
    get:
      tags:
      - Orders
      operationId: Get order status
      summary: Get order status
      description: Use this endpoint to check for the status and details of an order.
      parameters:
      - name: referenceId
        required: true
        in: path
        description: The unique payment attempt identifier generated by the POS terminal that was sent
          in the request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
        schema:
          type: string
          example: 352c530dd7f747161a5e6c990c720bec
      - name: Authorization
        in: header
        description: 'Header required for authorization. Specify the HMAC signature in the Authorization
          header along with `accessKeyId`.

          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 should be the same value used in the generation of the HMAC signature
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      - name: X-ShopBack-Idempotent-Id
        in: header
        description: Idempotent Id for the request. If this is absent,  every request will be treated
          as unique and will be processed as such. (This is optional for now, but will be made required
          in the future)
        schema:
          example: faa5e09a-8cf3-43f7-8309-d94deb426e66
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrderDetailsResDto'
        '400':
          description: ''
          content: {}
        '401':
          description: ''
          content: {}
        '404':
          description: ''
          content: {}
        '409':
          description: ''
          content: {}
      x-source-doc: https://docs.shopback.com/reference/get-order-status
  /<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
  /posi-sandbox/v1/instore/order/{referenceId}/refund:
    post:
      tags:
      - Orders
      operationId: Order refund
      summary: Order refund
      description: Use this endpoint to refund captured orders with ShopBack.
      parameters:
      - name: referenceId
        required: true
        in: path
        description: The unique payment attempt identifier generated by the POS terminal that was sent
          in the request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Header required for authorization. Specify the HMAC signature in the Authorization
          header along with `accessKeyId`.

          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 should be the same value used in the generation of the HMAC signature
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      - name: X-ShopBack-Idempotent-Id
        in: header
        description: Idempotent Id for the request. If this is absent,  every request will be treated
          as unique and will be processed as such. (This is optional for now, but will be made required
          in the future)
        schema:
          example: faa5e09a-8cf3-43f7-8309-d94deb426e66
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxRefundOrderReqDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundOrderResDto'
        '400':
          description: ''
          content: {}
        '401':
          description: ''
          content: {}
        '404':
          description: ''
          content: {}
        '409':
          description: ''
          content: {}
      x-source-doc: https://docs.shopback.com/reference/order-refund
  /posi-sandbox/v1/instore/order/scan:
    post:
      tags:
      - Orders
      operationId: Scan consumer QR
      summary: Scan consumer QR
      description: Use this endpoint to create an order to initiate payment using ShopBack’s consumer-presented
        QR code.
      parameters:
      - name: Authorization
        in: header
        description: 'Header required for authorization. Specify the HMAC signature in the Authorization
          header along with `accessKeyId`.

          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 should be the same value used in the generation of the HMAC signature
        required: true
        schema:
          type: string
          example: '2022-08-22T02:29:33.123Z'
      - name: X-ShopBack-Idempotent-Id
        in: header
        description: Idempotent Id for the request. If this is absent,  every request will be treated
          as unique and will be processed as such. (This is optional for now, but will be made required
          in the future)
        schema:
          example: faa5e09a-8cf3-43f7-8309-d94deb426e66
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxScanOrderReqDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResDto'
        '400':
          description: ''
          content: {}
        '401':
          description: ''
          content: {}
        '404':
          description: ''
          content: {}
        '409':
          description: ''
          content: {}
      x-source-doc: https://docs.shopback.com/reference/scan-consumer-qr
components:
  schemas:
    SandboxCancelOrderReqDto:
      type: object
      properties:
        reason:
          type: string
          description: The reason explaining cancellation.
          example: Incorrect amount
    CancelOrderResDto:
      type: object
      properties:
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
        referenceId:
          type: string
          description: The unique payment attempt identifier generated by the POS terminal that was sent
            in the request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
      required:
      - traceId
      - referenceId
    BadReqDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: string
          example: Invalid referenceId. Please provide a string value.
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
      required:
      - statusCode
      - message
      - traceId
    UnauthorizedDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          type: string
          example: Invalid signature. Failed to match HMAC signatures.
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
      required:
      - statusCode
      - message
      - traceId
    NotFoundResDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 404
        message:
          type: string
          example: Invalid posId. Unable to find matching posId.
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
      required:
      - statusCode
      - message
      - traceId
    ResouceConflictDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 409
        message:
          type: string
          example: Invalid ReferenceId. ReferenceId provided is already assigned to an existing resource.
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
      required:
      - statusCode
      - message
      - traceId
    SandboxCreateOrderReqDto:
      type: object
      properties:
        posId:
          type: string
          description: Unique Id for the POS terminal given during onboarding.
          example: 802c987em7f747269a5e6c260c630kpl
        country:
          type: string
          description: Two-letter ISO country code according to <a href=https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
            target="_blank">ISO 3166-1 Alpha-2</a> standard.
          example: SG
          enum:
          - SG
          - HK
          - AU
          - MY
        amount:
          type: number
          description: 'Transaction amount as integer. A positive integer in the smallest currency unit.
            For example:

            * `SGD`: in cents. 1234 stands for S$12.34'
          example: 1234
        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, in UPPERCASE.
          enum:
          - SGD
          - HKD
          - AUD
          - MYR
          example: SGD
        referenceId:
          type: string
          description: A unique payment identifier generated by the POS terminal. This must be unique
            for every payment attempt.
          example: 352c530dd7f747161a5e6c990c720bec
        qrType:
          type: string
          description: Type of QR.
          enum:
          - base64
          - payload
          - url_payload
          example: base64
        partner:
          description: Merchant information for ShopBack partner. Please sort keys in alphabetical order
            during hmac generation.
          $ref: '#/components/schemas/PartnerMerchantInfoRequest'
        orderMetadata:
          description: Additional information for the order. Please sort keys in alphabetical order during
            hmac generation.
          $ref: '#/components/schemas/AdditionalOrderMetadata'
        webhookUrl:
          description: The url to which ShopBack partner wants to receive payment notification webhook.
      required:
      - posId
      - country
      - amount
      - currency
      - referenceId
      - qrType
    CreateOrderResDto:
      type: object
      properties:
        referenceId:
          type: string
          description: The unique payment attempt identifier generated by the POS terminal that was sent
            in the request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
        qrType:
          type: string
          description: Type of QR code returned, as specified in request.
          enum:
          - base64
          - payload
          - url_payload
          example: base64
        qrCode:
          type: string
          description: Dynamic QR code according to qrType.
          example: data:image/png;base64,iVBORw0KGgoAAAAN...
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
        partner:
          description: Merchant information for ShopBack partner.
          $ref: '#/components/schemas/PartnerMerchantInfoRequest'
        orderMetadata:
          description: Additional information of the payment.
          $ref: '#/components/schemas/AdditionalOrderMetadata'
      required:
      - referenceId
      - qrType
      - qrCode
      - traceId
    PartnerMerchantInfoRequest:
      required:
      - merchantId
      type: object
      properties:
        merchantId:
          type: string
          description: Partner's unique merchant ID. This field is required if partner  field is provided
        merchantCategoryCode:
          type: number
          description: Merchant ISO 18245 category code determined by the partner
        merchantTradingName:
          type: string
          description: Trading name of the merchant to help with customer UX when completing  a purchase
            with ShopBack
        merchantEntityId:
          type: string
          description: Legally registered ID with the regulatory in country of registration
          example: UEN in Singapore
    AdditionalOrderMetadata:
      type: object
      properties:
        terminalReference:
          type: string
          description: External POS terminal used for the order determined by the partner. Numbers only,
            letters only, or alphanumeric with a length of 5-36 with only hypen is allowed as a special
            character.
          example: TW001271r-CEalBMhQw
        merchantOrderReference:
          type: string
          description: External merchant's order reference to identify specific order. Numbers only, letters
            only, or alphanumeric with a length of 5-36  with only hypen is allowed as a special character.
          example: 7YaEQwQi-3c6aRCJbz0N
    GetOrderDetailsResDto:
      type: object
      properties:
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
        createdAt:
          format: date-time
          type: string
          description: The timestamp of the payment attempt 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 payment attempt'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'
        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
        referenceId:
          type: string
          description: The unique payment attempt identifier generated by the POS terminal that was sent
            in the request parameters.
          example: 352c530dd7f747161a5e6c990c720bec
        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
        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: 0
        failureReason:
          type: string
          description: Reason for order failure, only provided if an order failed.
          example: ''
        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, in UPPERCASE.
          example: SGD
        partner:
          description: Merchant information for ShopBack partner.
          $ref: '#/components/schemas/PartnerMerchantInfoRequest'
        orderMetadata:
          description: Additional information of the payment.
          $ref: '#/components/schemas/AdditionalOrderMetadata'
        paymentType:
          type: string
          description: Customer’s payment type. Populated for completed and refunded orders only.
          readOnly: true
          example: PAY
          enum:
          - PAYLATER
          - PAY
      required:
      - traceId
      - createdAt
      - updatedAt
      - shopbackOrderId
      - referenceId
      - status
      - orderAmount
      - refundAmount
      - currency
      - paymentType
    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
    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
    SandboxRefundOrderReqDto:
      type: object
      properties:
        amount:
          type: number
          description: "The amount of refund being provided to the customer. This is provided as a positive\
            \ integer in the smallest currency unit and should not be larger than the order amount. For\
            \ example:\n\n    SGD: in cents. 1234 stands for S$12.34"
          example: 1234
        reason:
          type: string
          description: The reason for the refund.
          example: Wrong item charged
        referenceId:
          type: string
          description: The payment attempt identifier generated by the POS terminal that was sent in the
            request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
          example: 352c530dd7f747161a5e6c990c720bec
        posId:
          type: string
          description: Unique Id of the POS terminal used for the refund.
        refundMetadata:
          description: Additional refund metadata for the order. Please sort keys in alphabetical order
            during hmac generation.
          $ref: '#/components/schemas/AdditionalrefundMetadata'
      required:
      - amount
      - referenceId
    RefundOrderResDto:
      type: object
      properties:
        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
        referenceId:
          type: string
          description: The payment attempt identifier generated by the POS terminal that was sent in the
            request to `POST /v1/instore/order/create` or `POST /v1/instore/order/scan`.
        traceId:
          type: string
          description: A unique identifier for this API response. This will be used for reconciliation
            as necessary.
          example: 0dc44317-1c4b-4b62-83a8-8997435511e4
        posId:
          type: string
          description: Unique Id of the POS terminal used for the refund.
        refundMetadata:
          description: Additional refund metadata for the order.
          $ref: '#/components/schemas/AdditionalrefundMetadata'
      required:
      - shopbackOrderId
      - referenceId
      - traceId
    AdditionalrefundMetadata:
      type: object
      properties:
        terminalReference:
          description: External POS terminal used for the order determined by the partner. Numbers only,
            letters only, or alphanumeric with a length of 5-36 with only hypen is allowed as a special
            character.
          example: TW001271r-CEalBMhQw
    SandboxScanOrderReqDto:
      type: object
      properties:
        posId:
          type: string
          description: Unique Id for the POS terminal given during onboarding.
          example: 802c987em7f747269a5e6c260c630kpl
        country:
          type: string
          description: Two-letter ISO country code according to <a href=https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
            target="_blank">ISO 3166-1 Alpha-2</a> standard.
          example: SG
          enum:
          - SG
          - HK
          - AU
          - MY
        amount:
          type: number
          description: 'Transaction amount as integer. A positive integer in the smallest currency unit.
            For example:

            * `SGD`: in cents. 1234 stands for S$12.34'
          example: 1234
        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, in UPPERCASE.
          enum:
          - SGD
          - HKD
          - AUD
          - MYR
          example: SGD
        referenceId:
          type: string
          description: A unique payment identifier generated by the POS terminal. This must be unique
            for every payment attempt.
          example: 352c530dd7f747161a5e6c990c720bec
        consumerQrPayload:
          type: string
          description: Payload of the consumer-presented QR code scanned
          example: 0101234567890128TECI
        partner:
          description: Merchant information for ShopBack partner. Please sort keys in alphabetical order
            during hmac generation.
          $ref: '#/components/schemas/PartnerMerchantInfoRequest'
        orderMetadata:
          description: Additional information for the order. Please sort keys in alphabetical order during
            hmac generation.
          $ref: '#/components/schemas/AdditionalOrderMetadata'
        webhookUrl:
          description: The url to which ShopBack partner wants to receive payment notification webhook.
      required:
      - posId
      - country
      - amount
      - currency
      - referenceId
      - consumerQrPayload
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