Gift Card Balance Check

As part of utilising gift cards on your site and as part of the customers wallet you may wish to retrieve the current available balance for a gift card to display to a customer as well as calculate any split payments across the remaining balance of a gift card and another payment instrument type.

Balance by Gift Card Number & Pin

📘
Single vs. Multiple Card Balance Check
When checking a card balance by gift card number and pin, the service is restricted to only check a single instrument. When checking balance using a tokenized gift card's instrument ID, multiple gift card balances can be processed in a single call.

curl --location --request POST 'https://{{environment}}.wpay.com.au/wow/v1/pay/giftcards/balance' \
--header 'accept: application/json' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "giftCards": [
        {
            "cardNumber": "6280005563194014720",
            "pinCode": "5211"
        }        
    ]
}'

var myHeaders = new Headers();
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
myHeaders.append("accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);

var raw = JSON.stringify({
    "giftCards": [
        {
            "cardNumber": "628000*************",
            "pinCode": "5211"
        }        
    ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch(`https://${environment}.wpay.com.au/wow/v1/pay/giftcards/balance`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let yourAPIkey = "YOUR-API-KEY";
let environment = "substitute environment-value here"
let accessToken = "ACCESS-TOKEN";
let parameters = """
{\
  \"giftCards\": [\
      {\
          \"cardNumber\": \"62800*************\",\
          \"pinCode\": \"5211\"\
      }\
  ]\
}\
"""
let postData = parameters.data(using: .utf8)

var request = URLRequest(
  url: URL(string: "https://\(environment).wpay.com.au/wow/v1/pay/giftcards/balance")!,
  timeoutInterval: Double.infinity
)
request.addValue("application/json", forHTTPHeaderField: "accept")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue(yourAPIkey, forHTTPHeaderField: "X-Api-Key")
request.addValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY"
var accessToken = "ACCESS-TOKEN"
      
val response = khttp.post(
  url = "https://$environment" + 
        ".wpay.com.au/wow/v1/pay/giftcards/balance",
  headers = mapOf("accept" to "application/json",
                  "Content-Type" to "application/json",
                  "X-Api-Key" to yourAPIkey,
                  "Authorization" to "Bearer $accessToken"),
  json = mapOf(
    "giftCards" to arrayOf(
        mapOf(
            "cardNumber" to "628000*************",
            "pinCode" to "5211"
        )    
    )
  )
)

if(response.statusCode == 200) {
  val obj : JSONObject = response.jsonObject
  print(obj["giftCardBalances"])
} else {
  handleError(response)
}

Balance by Instrument ID

curl --location --request POST 'https://{{environment}}.wpay.com.au/wow/v1/pay/giftcards/balance' \
--header 'accept: application/json' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "giftCardInstruments": [
        {
            "paymentInstrumentId": "163****"
        }
    ]
}'

var myHeaders = new Headers();
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
myHeaders.append("accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);

var raw = JSON.stringify({
  "giftCardInstruments": [
    {
      "paymentInstrumentId": "163****"
    }
  ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch(`https://${environment}.wpay.com.au/wow/v1/pay/giftcards/balance`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let yourAPIkey = "YOUR-API-KEY";
let environment = "substitute environment-value here"
let accessToken = "ACCESS-TOKEN";
let parameters = """
{\
  \"giftCardInstruments\": [\
    {\
      \"paymentInstrumentId\": \"163****\"\
    }\
  ]\
}\
"""
let postData = parameters.data(using: .utf8)

var request = URLRequest(
  url: URL(string: "https://\(environment).wpay.com.au/wow/v1/pay/giftcards/balance")!,
  timeoutInterval: Double.infinity
)
request.addValue("application/json", forHTTPHeaderField: "accept")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue(yourAPIkey, forHTTPHeaderField: "X-Api-Key")
request.addValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY"
var accessToken = "ACCESS-TOKEN"
      
val response = khttp.post(
  url = "https://$environment" + 
        ".wpay.com.au/wow/v1/pay/giftcards/balance",
  headers = mapOf("accept" to "application/json",
                  "Content-Type" to "application/json",
                  "X-Api-Key" to yourAPIkey,
                  "Authorization" to "Bearer $accessToken"),
  json = mapOf(
    "giftCardInstruments" to arrayOf(
      mapOf(
        "paymentInstrumentId" to "163****"
      )
    )
  )
)

if(response.statusCode == 200) {
  val obj : JSONObject = response.jsonObject
    print(obj["giftCardBalances"])
} else {
  handleError(response)
}

Gift Card Balance Outcome

{
    "giftCardBalances": [
        {
            "cardNumber": "628000*************",
            "balance": 111.03,
            "expiryDay": "31",
            "expiryMonth": "12",
            "expiryYear": "2120",
            "expired": false
        }
    ]
}

Where:

balance is the remaining balance available for use on the gift card
expiryDay, expiryMonth & expiryYear provide the date on which the card is scheduled to expire
expired is a boolean which indicates whether the card is considered an expired card

Retrieve Gift Card Balance using List Instruments

You can also retrieve the balance of multiple gift cards in your wallet using Get Payment Instruments List by adding include=GC_BALANCE optional query parameter. Refer to Retrieve a Customers Wallet for more information about List Instruments.

curl --location \
--request GET 'https://{{environment}}.wpay.com.au/wow/v1/pay/instore/customer/instruments?include=GC_BALANCE' \
--header 'accept: application/json' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}' \
--header 'Content-Type: application/json' \

var myHeaders = new Headers();
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
myHeaders.append("accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

var environment = "substitute environment-value here"
fetch(`https://${environment}.wpay.com.au/wow/v1/pay/instore/customer/instruments?include=GC_BALANCE`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let yourAPIkey = "YOUR-API-KEY";
let environment = "substitute environment-value here"
let accessToken = "ACCESS-TOKEN";


var request = URLRequest(
  url: URL(string: "https://\(environment).wpay.com.au/wow/v1/pay/instore/customer/instruments?include=GC_BALANCE")!,
  timeoutInterval: Double.infinity
)
request.addValue("application/json", forHTTPHeaderField: "accept")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue(yourAPIkey, forHTTPHeaderField: "X-Api-Key")
request.addValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY"
var accessToken = "ACCESS-TOKEN"
      
val response = khttp.post(
  url = "https://$environment" + 
        ".wpay.com.au/wow/v1/pay/instore/customer/instruments?include=GC_BALANCE",
  headers = mapOf("accept" to "application/json",
                  "Content-Type" to "application/json",
                  "X-Api-Key" to yourAPIkey,
                  "Authorization" to "Bearer $accessToken")
)

if(response.statusCode == 200) {
  val obj : JSONObject = response.jsonObject
    print(obj["data"])
} else {
  handleError(response)
}

List Instrument including Gift Card Balance Outcome

{
    "data": {
        "creditCards": [],
        "giftCards": [
            {
                "paymentInstrumentId": "251****",
                "paymentToken": "a61aa56d-c9db-****-****-***********",
                "status": "VERIFIED",
                "createdOn": "2022-08-23T09:27:40.478+10:00",
                "lastUpdated": "2022-08-23T09:28:26.596+10:00",
                "lastUsed": "2022-08-23T09:28:26.105+10:00",
                "primary": true,
                "allowed": true,
                "programName": "Wish eGift Card",
                "cardSuffix": "8480",
                "stepUp": {
                    "type": "REQUIRE_PASSCODE",
                    "mandatory": false
                },
                "instrumentType": "GIFT_CARD",
                "balanceDetail": {
                    "balance": 709.45
                }
            },
            {
                "paymentInstrumentId": "251****",
                "paymentToken": "f896b20a-34c0-****-****-***********",
                "status": "UNVERIFIED_PERSISTENT",
                "createdOn": "2022-08-23T09:19:04.186+10:00",
                "lastUpdated": "2022-08-23T09:27:40.472+10:00",
                "primary": false,
                "allowed": true,
                "cardSuffix": "6401",
                "programName": "Wish eGift Card",
                "stepUp": {
                    "type": "REQUIRE_PASSCODE",
                    "mandatory": false
                },
                "instrumentType": "GIFT_CARD",
                "balanceDetail": {
                    "balance": 812.35
                }
            }
        ],
        "paymentAgreements": []
    },
    "meta": {}
}

Where:

paymentInstrumentId is the payment token of the associated gift card saved in the customer's wallet.
paymentToken is the payment token unique GUID of the associated gift card saved in the customer's wallet
status is either VERIFIED or UNVERIFIED_PERSISTENT. Verified indicates that a successful verification or purchase has occurred using the instrument. Unverified indicates that the card has not yet been verified or used in a purchase.
lastUpdated is the date the gift card information was last updated.
primary indicates whether the gift card is the primary instrument in the customer's wallet to make payments.
allowed indicates whether the gift card is an allowed payment method based on your merchant config with Wpay.
cardSuffix provides the last 4 digits of the tokenized gift card for display purposes.
programName is the gift card name given at the point of tokenization.
stepUp - mandatory will align with the stepUp - type indicator.
instrumentType is always GIFT_CARD for gift card instrument.
balanceDetail - balance is the remaining balance available for use on the gift card.

Balance by Gift Card Number & Pin

📘Single vs. Multiple Card Balance Check

Balance by Instrument ID

Gift Card Balance Outcome

Retrieve Gift Card Balance using List Instruments

List Instrument including Gift Card Balance Outcome

📘
Single vs. Multiple Card Balance Check