Batch Order

Suggest Edits

We recommend you use the batch order approach when ordering more than 10 gift cards at a time. Both real-time and batch orders invoke the same Order API but a batch order can process up to 25,000 cards.

When you submit a batch order, your order gets added to an internal queue for processing and you can monitor the progress of your order. Once your order has been processed successfully, you can retrieve your activated gift cards.

Similar to real-time orders, every batch order you place will be auto-debited from your SVA i.e. your available balance will be reduced by the order value and the outstanding balance will be increased by the order value

Step 1: Confirm Payment

  • Your customer navigates to your website, selects more than 10 gift cards to purchase and adds them to their cart before proceeding to checkout

  • You create a unique reference number for the order and process payment using your payment processor.

Step 2: Place Order

Once the you have confirmed payment from the customer, you invoke the Order API to order the gift cards

When invoking the Order API, pass in the unique reference number you created in Step 1

Make sure you set the syncOnly flag to false to trigger the order in batch mode.

curl --request POST \
     --url https://pt-api.wpay.com.au/v1/partner/giftcards/orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: **************' \
     --data '
{
     "payments": [
          {
               "code": "svc",
               "amount": 5
          }
     ],
     "products": [
          {
               "sku": "*********",
               "price": 5,
               "qty": 1000,
               "currency": "036"
          }
     ],
     "refno": "aaaa-bbbb-0000-0007",
     "syncOnly": false
}
'

Where:

  • refno is your unique order reference number
  • payments specifies that the payment will be made from your SVA
  • products contains the details of the gift cards to be purchased
    • sku is the gift card product identifier
    • price is the amount to be loaded onto the gift card
    • qty is the number of gift cards being ordered
  • syncOnly with a value of false requests that the order be processed in batch mode

We will acknowledge receipt of your batch order and begin creating your gift cards.

A successful response will have the HTTP status code of 202 and indicate your batch order is in processing status.

{
  "status": "PROCESSING",
  "orderId": "AAN9200073512",
  "refno": "aaaa-bbbb-0000-0007",
  "cancel": {
    "allowed": true,
    "allowedWithIn": 15
  },
  "currency": {
    "code": "AUD",
    "numericCode": "036",
    "symbol": "$"
  },
  "payments": [
    {
      "code": "svc"
    }
  ]
}

Where:

  • status contains the current status of your order
  • refno is your unique order reference number
  • orderId is the Wpay order identifier

The response contains the orderId which you will need to monitor the progress of your order as part of Step 3

Refer to the Order Digital Gift Cards API specification for descriptions of all fields in the request and response.

Step 3: Monitor Order Status

Once your batch order has been placed, you will need to track the progress of the order to know when processing has completed and your cards have been created so you can retrieve them.

You can use your order number from Step 2 to invoke the Order Status API and check the status of your order

curl --location --request GET 'https://pt-api.wpay.com.au/v1/partner/giftcards/order/{refno}/status' \
--header 'content-type: application/json' \
--header 'X-Api-Key: ************************'

Where:

  • refno is your unique order reference number

We recommend you periodically invoke the Order Status API while waiting 15 minutes between calls

  • Your order will initially have the status PENDING and then PROCESSING as your cards are prepared.
  • Your order status will change to COMPLETE when your order has been successfully processed

📘

Note

  • If you've ordered around 100 gift cards, we recommend that you periodically invoke the Order Status API while waiting 5 minutes between calls

  • If you've ordered around 5000 gift cards, we recommend that you periodically invoke the Order Status API while waiting 15 minutes between calls

  • If you've ordered around 10000 gift cards, we recommend that you periodically invoke the Order Status API while waiting 35 minutes between calls

  • If you've ordered around 20000 gift cards, we recommend that you periodically invoke the Order Status API while waiting 60 minutes between calls

{
  "status": "COMPLETE",
  "statusLabel": "Complete",
  "orderId": "AAN9200073512",
  "refno": "aaaa-bbbb-0000-0007",
  "cancel": {
    "allowed": true,
    "allowedWithIn": 15
  }
}

Where:

  • status contains the current status of your order
  • refno is your unique order reference number
  • orderId is the Wpay order identifier

Once your order status has changed to COMPLETE, your card details are ready to be retrieved via Step 4

Refer to the Get Order Status API specification for descriptions of all fields in the request and response.

Step 4 : Retrieve Card Details

You can retrieve your activated card details once your order has been processed successfully.

You can access your card details by invoking the Activated Cards API.

curl --location --request GET 'https://pt-api.wpay.com.au/v1/partner/giftcards/order/{orderId}/cards?offset=0&limit=100' \
--header 'content-type: application/json' \
--header 'X-Api-Key: ************************'

Where:

  • orderId is the Wpay order identifier returned when the order was placed.

A successful response will have the HTTP status code of 200 and contain all the gift cards that have been provisioned for you.

{
  "products": {
    "***********": {
      "sku": "***********",
      "name": "Woolworths eGift Card",
      "specialInstruction": "",
      "images": {
        "thumbnail": "https://gbdev.s3.amazonaws.com/anzuat/product/d/thumbnail/560_microsite.jpg",
        "mobile": "https://gbdev.s3.amazonaws.com/anzuat/product/d/mobile/560_microsite.jpg",
        "base": "https://gbdev.s3.amazonaws.com/anzuat/product/d/image/560_microsite.jpg",
        "small": "https://gbdev.s3.amazonaws.com/anzuat/product/d/small_image/560_microsite.jpg"
      },
      "cardBehaviour": "QC"
    }
  },
  "cards": [
    {
      "sku": "WWQ651BHNWSH",
      "productName": "Woolworths eGift Card",
      "labels": {
        "cardNumber": "Gift Card Number",
        "cardPin": "Card PIN",
        "activationCode": "Activation Code",
        "validity": "Validity"
      },
      "cardNumber": "*******************",
      "cardPin": "****",
      "activationCode": null,
      "barcode": "*********************************",
      "activationUrl": null,
      "formats": [
        {
          "key": "CNONLY",
          "value": "*******************"
        },
        {
          "key": "QCGTINBARCODE-32",
          "value": "*********************************"
        }
      ],
      "amount": "5.00",
      "validity": "2023-05-04T18:30:00+00:00",
      "issuanceDate": "2022-05-05T05:43:07+00:00",
      "cardId": 378470,
      "recipientDetails": {
        "salutation": null,
        "name": "JANE SMITH",
        "firstname": "JANE",
        "lastname": "SMITH",
        "email": "[email protected]",
        "mobileNumber": "+61************",
        "status": "",
        "failureReason": "",
        "delivery": {
          "mode": "API",
          "status": {
            "sms": {
              "status": "NA",
              "reason": "NA"
            },
            "email": {
              "status": "NA",
              "reason": "NA"
            }
          }
        }
      },
      "theme": ""
    },{
      "sku": "WWQ651BHNWSH",
      "productName": "Woolworths eGift Card",
      "labels": {
        "cardNumber": "Gift Card Number",
        "cardPin": "Card PIN",
        "activationCode": "Activation Code",
        "validity": "Validity"
      },
      "cardNumber": "*******************",
      "cardPin": "****",
      "activationCode": null,
      "barcode": "*********************************",
      "activationUrl": null,
      "formats": [
        {
          "key": "CNONLY",
          "value": "*******************"
        },
        {
          "key": "QCGTINBARCODE-32",
          "value": "*********************************"
        }
      ],
      "amount": "5.00",
      "validity": "2023-05-04T18:30:00+00:00",
      "issuanceDate": "2022-05-05T05:43:07+00:00",
      "cardId": 378470,
      "recipientDetails": {
        "salutation": null,
        "name": "JANE SMITH",
        "firstname": "JANE",
        "lastname": "SMITH",
        "email": "[email protected]",
        "mobileNumber": "+61************",
        "status": "",
        "failureReason": "",
        "delivery": {
          "mode": "API",
          "status": {
            "sms": {
              "status": "NA",
              "reason": "NA"
            },
            "email": {
              "status": "NA",
              "reason": "NA"
            }
          }
        }
      },
      "theme": ""
    },{
      "sku": "WWQ651BHNWSH",
      "productName": "Woolworths eGift Card",
      "labels": {
        "cardNumber": "Gift Card Number",
        "cardPin": "Card PIN",
        "activationCode": "Activation Code",
        "validity": "Validity"
      },
      "cardNumber": "*******************",
      "cardPin": "****",
      "activationCode": null,
      "barcode": "*********************************",
      "activationUrl": null,
      "formats": [
        {
          "key": "CNONLY",
          "value": "*******************"
        },
        {
          "key": "QCGTINBARCODE-32",
          "value": "*********************************"
        }
      ],
      "amount": "5.00",
      "validity": "2023-05-04T18:30:00+00:00",
      "issuanceDate": "2022-05-05T05:43:07+00:00",
      "cardId": 378470,
      "recipientDetails": {
        "salutation": null,
        "name": "JANE SMITH",
        "firstname": "JANE",
        "lastname": "SMITH",
        "email": "[email protected]",
        "mobileNumber": "+61************",
        "status": "",
        "failureReason": "",
        "delivery": {
          "mode": "API",
          "status": {
            "sms": {
              "status": "NA",
              "reason": "NA"
            },
            "email": {
              "status": "NA",
              "reason": "NA"
            }
          }
        }
      },
      "theme": ""
    },
    //... all 100 requested cards will be returned
  ],
  "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": 1
}

The response contains two key sets of information:

  • The 'cards' field contains the card details of every gift card created
  • The 'products' field contains SKU data for each SKU ordered.

Refer to the Get Activated Cards API specification for descriptions of all fields in the request and response.

📘

Note

  • When ordering more than 100 gift cards, use pagination to call the Activated Cards API to retrieve 100 gift cards at a time.

  • You can retrieve the next set of 100 cards, by incrementing the offset parameter by 100 and leaving the limit parameter at 100.

  • When ordering more than 500 cards, use pagination to call the Activated Cards API in a loop with a maximum limit of 500 records until all cards are retrieved.

curl --location --request GET 'https://pt-api.wpay.com.au/v1/partner/giftcards/order/{orderId}/cards?offset=100&limit=100' \
--header 'content-type: application/json' \
--header 'X-Api-Key: ************************'

Where:

  • orderId is the Wpay order identifier returned when the order was placed.
  • offset is the starting record number
  • limit is the number of cards to retrieve

The system will respond with a 201 and the details of the next 100 cards. Continue this process until all cards are retrieved.

Step 5 : Fulfill Order

Once your order has been processed successfully, you can choose to communicate the activated card details to the customer via your existing business process i.e. email or text message.

Updated 3 months ago