Batch Order
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 numberpayments
specifies that the payment will be made from your SVAproducts
contains the details of the gift cards to be purchasedsku
is the gift card product identifierprice
is the amount to be loaded onto the gift cardqty
is the number of gift cards being ordered
syncOnly
with a value offalse
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 orderrefno
is your unique order reference numberorderId
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 thenPROCESSING
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 orderrefno
is your unique order reference numberorderId
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 thelimit
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 numberlimit
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 8 months ago