Woolworths Group Ordering Digital Gift Cards API

openapi: 3.2.0
info:
  title: WPay External Partner Integration Ordering Digital Gift…
  description: Gift Card API for External Partner Integration
  version: 1.2.0
servers:
- url: https://pt-api.wpay.com.au/v1/partner/giftcards
  description: Integration environment
security:
- X-Api-Key: []
tags:
- name: Ordering Digital Gift Cards
paths:
  /order/{orderId}/cards:
    get:
      summary: Get Activated Cards
      operationId: getActivatedGiftCards
      description: This API allows you to retrieve activated card details. It is the final step in the batch order process. This API can also be used in the recovery of a real-time order error, where the order status is `COMPLETE`.
      tags:
      - Ordering Digital Gift Cards
      parameters:
      - name: orderId
        description: Wpay order identifier (ID). Use the order ID that is returned in the digital gift card order response.
        schema:
          type: number
        in: path
        required: true
        example: AAN9200073512
      - name: offset
        description: The starting offset at which the cards should be retrieved. The first card has an offset of 0. If the value is not supplied the default value of 0 is used.
        required: false
        example: 0
        schema:
          type: number
          minimum: 0
        in: query
      - name: limit
        description: The maximum number of records to retrieve. Used in conjunction with offset to achieve pagination of resuts.
        required: false
        example: 100
        schema:
          type: number
          minimum: 1
          maximum: 500
        in: query
      responses:
        '200':
          description: This successful response will contain the card details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivatedCardsResponse'
        '400':
          description: This response code indicates that an error was encountered when retrieving the card details. The cause will be a validation problem or logic rule.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BusinessLogicErrorResponse'
        '500':
          description: This response code indicates that an unexpected error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /order/{refno}/status:
    get:
      summary: Get Order Status
      operationId: getGiftCardOrderStatus
      description: This API allows you to retrieve the status of an order. It is used in the batch order process to monitor the progress of the order. It is also used in the real-time order process to recover from situations where a timeout or unexpected error occurs. The order status will determine if the order has succeeded and you may get the activated cards, or has failed and should be re-tried.
      tags:
      - Ordering Digital Gift Cards
      parameters:
      - name: refno
        description: The unique order reference identifier you supplied when ordering the digital gift cards.
        schema:
          type: string
          maxLength: 55
        in: path
        required: true
        example: aaaa-bbbb-0000-0001
      responses:
        '200':
          description: when Order status in response is Completed, activated cards api to be called to get the card information. If Order status in response is Processing or Canceled, then refund can be processed to the customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '400':
          description: This response code indicates that an error was encountered when retrieving the order status. The cause will be a validation problem or logic rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLogicErrorResponse'
        '500':
          description: This response code indicates that an unexpected error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders:
    post:
      summary: Order Digital Gift Cards
      operationId: orderGiftCards
      description: This API allows you to place an order for one or more digital gift cards. The endpoint can operate in both real-time and batch modes. Consult the usage guide for information about these two order types and the type-specific sequence of events.
      tags:
      - Ordering Digital Gift Cards
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DigitalOrderRequest'
        required: true
      responses:
        '201':
          description: This response code indicates that the real-time digital gift card order has been successfully submitted and the cards details have been returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDigitalCardsResponse'
        '202':
          description: This response code indicates that the batch digital gift card order has been successfully submitted. The response will include the current order status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderProcessingResponse'
        '400':
          description: This response code indicates that an error was encountered when submitting the order. The cause will be a validation problem or logic rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLogicErrorResponse'
        '500':
          description: This response code indicates that an unexpected error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderProcessingResponse:
      type: object
      description: Order Status Response
      properties:
        status:
          type: string
          description: This indicates the current order status. The value will be 'PROCESSING' in a batch order.
          example: PROCESSING
        orderId:
          type: string
          description: Wpay order identifier (ID). This order ID is used at the end the batch order process when retrievig the ativated cards.
          example: AAN9200073512
        refno:
          type: string
          description: Your unique order reference identifier that was supplied in the request. This identifier is used to retrieve the order status.
          example: aaaa-bbbb-0000-0001
        cancel:
          $ref: '#/components/schemas/cancelObject'
        currency:
          $ref: '#/components/schemas/currencyObject'
        payments:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: svc
      example:
        status: PROCESSING
        orderId: AAN9200073512
        refno: aaaa-bbbb-0000-0001
        cancel:
          allowed: false
          allowedWithIn: 15
        currency:
          code: NZD
          numericCode: '554'
          symbol: NZ$
        payments:
        - code: svc
    productsMapObject:
      type: object
      required:
      - default
      properties:
        sku:
          type: string
          description: The product identifier (SKU). One item in the map will be present for each unique SKU.
      additionalProperties:
        type: object
        description: Product information, including artwork for each gift card SKU ordered.
        minItems: 1
        maxItems: 1
        required:
        - cardBehaviour
        - barcodeFormats
        properties:
          sku:
            type: string
            description: The product identifier (SKU). This field is a repeat of the hash map key.
            example: WOOHOO
          name:
            type: string
            description: The product name
            example: Active Product
          balanceEnquiryInstruction:
            type: string
            description: This field is unused.
            example: null
          specialInstruction:
            description: This field is unused.
            oneOf:
            - type: string
              default: ''
            - type: object
              properties:
                label:
                  type: string
                  description: This field is unused.
                url:
                  type: string
                  description: This field is unused.
            type: string
          images:
            type: object
            description: This field is unused.
            properties:
              base:
                type: string
                example: https://d1o7uku192uawx.cloudfront.net/mobile/media/cardimage/WoohooW_312×200.png
              small:
                type: string
                example: https://d1o7uku192uawx.cloudfront.net/mobile/media/cardimage/WoohooW_312×200.png
              thumbnail:
                type: string
                example: https://d1o7uku192uawx.cloudfront.net/mobile/media/cardimage/WoohooW_312×200.png
              mobile:
                type: string
                example: https://d1o7uku192uawx.cloudfront.net/mobile/media/cardimage/WoohooW_312×200.png
          cardBehaviour:
            type: string
            description: This field is unused.
            example: QC BHNDIGITAL
    cardPurchaseObject:
      type: object
      required:
      - sku
      - price
      - qty
      - currency
      properties:
        sku:
          type: string
          description: The gift card identifier (SKU). The list of gift cards you may order will be predefined and shared during the onboarding process.
          example: WOOHOO
        price:
          type: number
          description: The currency amount to load onto the gift card.
          example: 5
        qty:
          type: number
          description: The number of gift cards you wish to order with this SKU and price combination.
          example: 1
        currency:
          type: string
          description: Use 036 for AUD currency. The full list of valid codes is defined at  https://en.wikipedia.org/wiki/ISO_4217
          minLength: 3
          maxLength: 3
          example: '036'
    paymentsResponseObject:
      description: The account the gift card amounts have or will be deducted from.
      type: array
      items:
        type: object
        properties:
          code:
            type: string
            description: The code 'svc' indicates that the payment was be made against your SVA.
            example: svc
          balance:
            type: number
            description: The payment amount for the order. This value will match the sum of 'price' times 'qty' for all cards in this order.
            example: 5
    BusinessLogicErrorResponse:
      required:
      - code
      type: object
      description: Payload for a business logic error
      properties:
        httpStatusCode:
          type: number
          description: The http status code
          example: 400
        errorCode:
          type: string
          description: The error code
          example: '5313'
        errorMessage:
          type: string
          description: The error message
          example: Duplicate reference number provided
        messages:
          type: array
          items:
            type: string
        additionalTxnFields:
          type: object
          properties:
            responseCode:
              type: number
              example: 10004
      example:
        httpStatusCode: 400
        errorCode: '5313'
        errorMessage: Duplicate reference number provided
        messages: []
        additionalTxnFields:
          responseCode: 10004
    paymentsObject:
      description: The account the gift card amounts will be deducted from. Requires one single element to indicate the payment will be made using the SVA.
      type: array
      minItems: 1
      maxItems: 1
      items:
        required:
        - code
        - amount
        type: object
        properties:
          code:
            type: string
            description: Always use the code 'svc'.
            example: svc
            default: svc
            enum:
            - svc
          amount:
            type: number
            description: The payment amount for the order. This value must match the sum of 'price' times 'qty' for all cards in this order.
            example: 5
    DigitalOrderRequest:
      required:
      - payments
      - products
      - refno
      - syncOnly
      - deliveryMode
      type: object
      properties:
        payments:
          $ref: '#/components/schemas/paymentsObject'
        products:
          description: The details of the gift card(s) that you wish to order.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/cardPurchaseObject'
        refno:
          type: string
          description: A unique order reference identifier you generate and supply. This identifier is used in the batch order process when retreiving order status. It is also used in real-time orders during the error recovery process.
          maxLength: 55
          example: aaaa-bbbb-0000-0001
        syncOnly:
          type: boolean
          description: Indicates if the order shall be processed in real-time or in batch mode. Supply `true` to process in real-time. Supply `false` to process as a batch. Note, there is a 10 card limit on real-time orders. Consult the usage guide for information about these two order types and the type-specific sequence of events.
          example: true
        deliveryMode:
          type: string
          description: This field is used to specify how the gift card details will be delivered. Only ‘API’ is supported.
          example: API
          default: API
          enum:
          - API
      description: The JSON request structure of the Order endpoint.
      example:
        payments:
        - code: svc
          amount: 200
        products:
        - sku: WSTEST001
          price: 100
          qty: 2
          currency: '036'
        refno: aaaa-bbbb-0000-0001
        syncOnly: true
        deliveryMode: API
    Error:
      required:
      - httpStatusCode
      - errorCode
      - errorMessage
      - errorDetail
      type: object
      description: Payload for an unexpected error
      properties:
        httpStatusCode:
          type: number
          description: The http status code (5xx HTTP status codes).
          example: 500
        errorCode:
          type: string
          description: The error code.
          example: AP99
        errorMessage:
          type: string
          description: The error message.
          example: Internal Server Error
        errorDetail:
          type: string
          description: The error detail.
          example: 'Oops! An error has occurred: ScriptExecutionFailed'
      example:
        httpStatusCode: 500
        errorCode: AP99
        errorMessage: Internal Server Error
        errorDetail: 'Oops! An error has occurred: ScriptExecutionFailed'
    OrderStatusResponse:
      type: object
      properties:
        status:
          type: string
          description: The current order status. Will be one of PENDING, PROCESSING, CANCELED and COMPLETE. PENDING indicates that the order has been placed but payment redepmtion and process has not yet begun. PROCESSING indicates that the order is currently being processed. CANCELED indicates that the order is canceled and the payment has been reversed. COMPLETE indicates that the gift card details are ready for retrieval via the Get Activated Cards API.
          example: COMPLETE
          enum:
          - PENDING
          - PROCESSING
          - CANCELED
          - COMPLETE
        statusLabel:
          type: string
          description: Human readable description of the order status
          example: Complete
        orderId:
          type: string
          description: Wpay order identifier (ID). This order ID is used at the end the batch order process when retrievig the ativated cards.
          example: AAN9200073512
        refno:
          type: string
          description: The unique order reference identifier you supplied for this order.
          maxLength: 55
          example: aaaa-bbbb-0000-0001
      description: The JSON response structure of Order Status endpoint
      example:
        status: COMPLETE
        orderId: AAN9200073512
        refno: aaaa-bbbb-0000-0001
    cancelObject:
      type: object
      description: This field is unused.
      properties:
        allowed:
          type: boolean
          example: false
        allowedWithIn:
          type: number
          example: 15
    OrderDigitalCardsResponse:
      description: Real-Time Order Response
      required:
      - currency
      type: object
      properties:
        status:
          type: string
          description: This indicates the current order status. The value will be 'COMPLETE' in a real-time order.
          example: COMPLETE
        orderId:
          type: string
          description: Wpay order identifier (ID).
          example: AAN9200073512
        refno:
          type: string
          maxLength: 55
          description: The unique order reference identifier you supplied when ordering the digital gift cards.
          example: aaaa-bbbb-0000-0001
        payments:
          $ref: '#/components/schemas/paymentsResponseObject'
        currency:
          $ref: '#/components/schemas/currencyObject'
        cards:
          type: array
          description: This element will be present if this is a real-time order (syncOnly is true) and the deliveryMode is API.
          items:
            $ref: '#/components/schemas/cardDetailsObject'
        products:
          $ref: '#/components/schemas/productsMapObject'
          description: This field will be present only if syncOnly is true and delivery Mode is API. This field is a map of type string/object. The key is the product identifier (SKU), while the value is an object representing the product attributes.
        cancel:
          $ref: '#/components/schemas/cancelObject'
      example:
        status: COMPLETE
        orderId: AAN9200073512
        refno: aaaa-bbbb-0000-0001
        cancel:
          allowed: true
          allowedWithIn: 7
        currency:
          code: AUD
          numericCode: '036'
          symbol: $
        payments:
        - code: svc
        cards:
        - sku: WSTEST001
          productName: Woolworths Supermarket eGift Card - Test
          labels:
            cardNumber: Gift Card Number
            cardPin: Card PIN
            activationCode: Activation Code
            validity: null
          cardNumber: '6280000025184229376'
          cardPin: '1821'
          activationCode: null
          barcode: ''
          activationUrl: null
          formats:
          - key: CNONLY
            value: '6280000025184229376'
          - key: QCGTINBARCODE-32
            value: '93396872125766280000025184229376'
          amount: '100.00'
          validity: null
          cardId: 28753
          recipientDetails:
            name: JOHN DEO
            firstname: JOHN
            lastname: DEO
            email: JOHN.DEO@WOOLIES.COM
            mobileNumber: '+6100000000'
            status: ''
            failureReason: ''
            delivery:
              mode: ANY
              status:
                sms:
                  status: NA
                  reason: NA
                email:
                  status: NA
                  reason: NA
          theme: ''
        - sku: WSTEST001
          productName: Woolworths Supermarket eGift Card - Test
          labels:
            cardNumber: Gift Card Number
            cardPin: Card PIN
            activationCode: Activation Code
            validity: null
          cardNumber: '6280000023218852864'
          cardPin: '1443'
          activationCode: null
          barcode: ''
          activationUrl: null
          formats:
          - key: CNONLY
            value: '6280000023218852864'
          - key: QCGTINBARCODE-32
            value: '93396872125766280000023218852864'
          amount: '100.00'
          validity: null
          cardId: 28754
          recipientDetails:
            name: JOHN DEO
            firstname: JOHN
            lastname: DEO
            email: JOHN.DEO@WOOLIES.COM
            mobileNumber: '+91000000000'
            status: ''
            failureReason: ''
            delivery:
              mode: ANY
              status:
                sms:
                  status: NA
                  reason: NA
                email:
                  status: NA
                  reason: NA
          theme: ''
        products:
          WSTEST001:
            sku: WSTEST001
            name: Woolworths Supermarket eGift Card - Test
            balanceEnquiryInstruction: null
            specialInstruction: ''
            images:
              thumbnail: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/thumbnail/503_microsite.jpg
              mobile: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/mobile/503_microsite.jpg
              base: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/image/503_microsite.jpg
              small: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/small_image/503_microsite.jpg
            cardBehaviour: QC
        additionalTxnFields: []
    currencyObject:
      type: object
      description: Contains details about the gift card currency.
      properties:
        code:
          type: string
          description: Currency code
          example: AUD
        numericCode:
          type: string
          minLength: 3
          maxLength: 3
          description: Currency numeric code as per https://en.wikipedia.org/wiki/ISO_4217
          example: '036'
        symbol:
          type: string
          description: Currency symbol
          example: $
    ActivatedCardsResponse:
      type: object
      required:
      - deliveryMode
      - barcodeFormats
      properties:
        products:
          $ref: '#/components/schemas/productsMapObject'
          description: This field is a map of type string/object. The key is the product identifier (SKU), while the value is an object representing the product attributes.
        cards:
          type: array
          description: This array contains the details of each activated gift card.
          items:
            $ref: '#/components/schemas/cardDetailsObject'
        currency:
          $ref: '#/components/schemas/currencyObject'
        deliveryMode:
          type: string
          description: Delivery mode
        total_cards:
          type: number
          description: The total number of activated cards in this order. Use this in conjuntion with the offset and limit request parameters to achieve pagination.
          example: 100
      example:
        products:
          WSTEST001:
            sku: WSTEST001
            name: Woolworths Supermarket eGift Card - Test
            balanceEnquiryInstruction: null
            specialInstruction: ''
            images:
              thumbnail: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/thumbnail/503_microsite.jpg
              mobile: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/mobile/503_microsite.jpg
              base: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/image/503_microsite.jpg
              small: https://gbdev.s3.amazonaws.com/anzuat/product/WSTEST001/d/small_image/503_microsite.jpg
            cardBehaviour: QC
        cards:
        - sku: WSTEST001
          productName: Woolworths Supermarket eGift Card - Test
          labels:
            cardNumber: Gift Card Number
            cardPin: Card PIN
            activationCode: Activation Code
            validity: null
          cardNumber: '6280000025184229376'
          cardPin: '1821'
          activationCode: null
          barcode: ''
          activationUrl: null
          formats:
          - key: CNONLY
            value: '6280000025184229376'
          - key: QCGTINBARCODE-32
            value: '93396872125766280000025184229376'
          amount: '100.00'
          validity: null
          cardId: 28753
          recipientDetails:
            name: PARAMASIVAN K
            firstname: PARAMASIVAN
            lastname: K
            email: PARAMASIVAN.K@QWIKCILVER.COM
            mobileNumber: '+919066656413'
            status: ''
            failureReason: ''
            delivery:
              mode: ANY
              status:
                sms:
                  status: NA
                  reason: NA
                email:
                  status: NA
                  reason: NA
          theme: ''
        - sku: WSTEST001
          productName: Woolworths Supermarket eGift Card - Test
          labels:
            cardNumber: Gift Card Number
            cardPin: Card PIN
            activationCode: Activation Code
            validity: null
          cardNumber: '6280000023218852864'
          cardPin: '1443'
          activationCode: null
          barcode: ''
          activationUrl: null
          formats:
          - key: CNONLY
            value: '6280000023218852864'
          - key: QCGTINBARCODE-32
            value: '93396872125766280000023218852864'
          amount: '100.00'
          validity: null
          cardId: 28754
          recipientDetails:
            name: PARAMASIVAN K
            firstname: PARAMASIVAN
            lastname: K
            email: PARAMASIVAN.K@QWIKCILVER.COM
            mobileNumber: '+919066656413'
            status: ''
            failureReason: ''
            delivery:
              mode: ANY
              status:
                sms:
                  status: NA
                  reason: NA
                email:
                  status: NA
                  reason: NA
          theme: ''
        currency:
          code: AUD
          numericCode: '036'
          symbol: $
        deliveryMode: API
        delivery:
          summary:
            inProgress: 0
            sent: 0
            delivered: 0
            failed: 0
            email:
              totalCount: 0
              delivered: 0
              failed: 0
              inProgress: 0
            sms:
              totalCount: 0
              delivered: 0
              failed: 0
              inProgress: 0
            totalCardsCount: 0
        total_cards: 2
    cardDetailsObject:
      type: object
      properties:
        sku:
          type: string
          description: The gift card identifier.
          example: WOOHOO
        productName:
          type: string
          description: The name of the gift card
          example: Active Product
        labels:
          type: object
          required:
          - cardNumber
          - cardPin
          - activationCode
          properties:
            cardNumber:
              type: string
              description: The human readable label for the card number
              example: Gift Card Number
            cardPin:
              type: string
              description: The human readable label for the card PIN
              example: Gift Card Pin
            activationCode:
              type: string
              description: The human readable label for the card activation code
              example: Alternative for pin
            validity:
              type: string
              description: The human readable label for the card validity
              example: null
        cardNumber:
          type: string
          description: The gift card number
          example: '4700001230064884'
        cardPin:
          type: string
          description: The gift card PIN
          example: '1234'
        activationCode:
          type: string
          description: The gift card activation code
          example: '12147000012300'
        activationUrl:
          type: string
          description: The URL of the gift card activation page
          example: https://{baseUrl}/claim/470000/a/7SfzYJxRusNzctUk
        barcode:
          type: string
          description: The gift card barcode
          example: '1234567899000002223896157184'
        formats:
          type: array
          description: A list of barcode formats for this card. Each item in the list is a key/value pair.
          items:
            type: object
            properties:
              key:
                type: string
                description: The barcode format.
                example: CA128
                enum:
                - CNONLY
                - CA128
                - QRCODE
                - PDF417
                - INT2OF5
                - DATAMATRIX
                - QCGTINBARCODE-32
                - QCBARCODE-31-V1
                - TRACK2
              value:
                type: string
                description: The barcode value for this format. The field type is a string, althought the content of this string is a decimal.
                example: '93396872125766280000025184229376'
        amount:
          type: string
          description: The amount loaded onto the card.
        validity:
          type: string
          description: The expiry date of the gift card in (ISO 8601) format.
          example: '2020-10-21T00:00:00+00:00'
        issuanceDate:
          type: string
          description: The date the gift card was activated in (ISO 8601) format.
          example: '2020-10-21T00:00:00+00:00'
        cardId:
          type: number
          description: This field is unused.
        theme:
          type: string
          description: This field is unused.
        recipientDetails:
          type: object
          description: This field is unused.
          properties:
            name:
              type: string
              description: Recipient full name
              example: ABC XYZ
            firstname:
              type: string
              description: Recipient first name
              example: ABC
            lastname:
              type: string
              description: Recipient last name
              example: XYZ
            email:
              type: string
              description: Recipient email address
              example: abc@xyz.com
            mobileNumber:
              type: string
              description: Recipient mobile phone number
              example: '+911234567890'
            status:
              type: string
              description: Message delivery status
              example: SENT
  securitySchemes:
    X-Api-Key:
      type: apiKey
      name: X-Api-Key
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: true
x-assembled-from:
  note: Merged verbatim from the per-operation OpenAPI definitions Wpay (Woolworths Group payments business) embeds in each ReadMe reference page; raw pages saved under openapi/_original/wpay-developerhub/.
  retrieved: '2026-10-22'
  sources:
  - https://developerhub.wpay.com.au/giftingservices/reference/activatephysicalgiftcard.md
  - https://developerhub.wpay.com.au/giftingservices/reference/getactivatedgiftcards.md
  - https://developerhub.wpay.com.au/giftingservices/reference/getgiftcardorderstatus.md
  - https://developerhub.wpay.com.au/giftingservices/reference/getservicehealth.md
  - https://developerhub.wpay.com.au/giftingservices/reference/ordergiftcards.md
  - https://developerhub.wpay.com.au/giftingservices/reference/postordersreverse.md