Retrieve a Customers Wallet
Get a list of instruments for your customer
Where a registered customer has saved a payment instrument to their wallet during payment you are able to retrieve these saved payment instruments during subsequent checkouts allowing for easy checkout using saved payment details.
The wallet stores all tokenized payment instruments for your customer along with any configured payment agreements set up for recurring payments. This allows for simple checkout using an already saved payment method.
List Instruments
A list of saved payment instruments with you can be retrieved using the list instrument feature.
curl --location --request GET 'https://{{environment}}.wpay.com.au/wow/v1/pay/instore/customer/instruments' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}' \
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("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch(`https://${environment}.wpay.com.au/wow/v1/pay/instore/customer/instruments`, 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")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "accept")
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 yourAPIkey = "YOUR-API-KEY"
var environment = "substitute environment-value here"
var accessToken = "ACCESS-TOKEN"
val response = khttp.get(
url = "https://$environment" +
".wpay.com.au/wow/v1/pay/instore/customer/instruments",
headers = mapOf("Content-Type" to "application/json",
"X-Api-Key" to yourAPIkey,
"Authorization", "Bearer $accessToken")
)
if(response.statusCode == 200) {
val obj : JSONObject = response.jsonObject
println("""Successful response payload: ${obj["data"]}""")
} else {
handleError(response)
}
Your customers saved instruments and payment agreements will be returned and allow you to show their saved instruments for selection during checkout.
{
"data": {
"creditCards": [
{
"paymentInstrumentId": "213###",
"paymentToken": "7578a5bc-0aaa-####-####-############",
"status": "VERIFIED",
"createdOn": "2021-09-07T15:45:39.311+10:00",
"lastUpdated": "2021-09-20T16:50:03.090+10:00",
"lastUsed": "2021-09-20T16:50:02.592+10:00",
"primary": false,
"allowed": true,
"scheme": "MASTERCARD",
"cardSuffix": "0407",
"cardName": "CHAPMAN",
"expiryMonth": "01",
"expiryYear": "23",
"cvvValidated": false,
"expired": false,
"requiresCVV": true,
"updateURL": "https://iframe.environment.payments.woolworths.com.au/container-ws/getCaptureFrame/cvvExpiry/4f71251c-788a-####-####-############/213###",
"stepUp": {
"type": "CAPTURE_CVV",
"mandatory": true,
"url": "https://iframe.environment.payments.woolworths.com.au/container-ws/getCaptureFrame/cvv/4f71251c-788a-####-####-############/213###",
"sessionId": "4f71251c-788a-####-####-############"
}
},
{
"paymentInstrumentId": "214###",
"paymentToken": "c8b3cb08-f2b2-####-####-############",
"status": "UNVERIFIED_PERSISTENT",
"createdOn": "2021-09-22T16:24:32.622+10:00",
"lastUpdated": "2021-09-22T16:24:32.622+10:00",
"primary": false,
"allowed": true,
"expiryYear": "23",
"scheme": "VISA",
"expiryMonth": "02",
"cardName": "My Card",
"cardSuffix": "0608",
"cvvValidated": false,
"expired": false,
"requiresCVV": true,
"updateURL": "https://iframe.environment.payments.woolworths.com.au/container-ws/getCaptureFrame/cvvExpiry/4f71251c-788a-####-####-############/214###",
"stepUp": {
"type": "CAPTURE_CVV",
"mandatory": true,
"url": "https://iframe.environment.payments.woolworths.com.au/container-ws/getCaptureFrame/cvv/4f71251c-788a-####-####-############/214###",
"sessionId": "4f71251c-788a-####-####-############"
}
}
],
"giftCards": [],
"payPal": [
{
"paymentInstrumentId": "249###",
"paymentToken": "cc92c900-cce3-####-####-############",
"status": "VERIFIED",
"createdOn": "2021-08-19T12:22:44.247+10:00",
"lastUpdated": "2021-08-19T12:23:05.243+10:00",
"lastUsed": "2021-08-25T18:17:41.825+10:00",
"primary": true,
"allowed": true,
"customerId": "503088175",
"payPalId": "[email protected]"
}
],
"paymentAgreements": [{
"paymentInstrumentId": "213###",
"paymentToken": "4ad0927e-4eb2-####-####-############",
"status": "VERIFIED",
"createdOn": "2021-09-22T17:04:57.703+10:00",
"lastUpdated": "2021-09-22T17:04:57.703+10:00",
"primary": false,
"allowed": true,
"chargeCycle": "0",
"endDate": "2022-11-03T00:59:59.999",
"type": "RECURRING",
"chargeAmount": 99.99,
"chargeFrequency": "WEEKLY",
"startDate": "2021-09-22T17:04",
"cardSuffix": "0407",
"expiryMonth": "01",
"expiryYear": "23",
"scheme": "MASTERCARD",
"expired": false,
"updateURL": "https://environment.wpay.com.au/wow/v1/pay/paymentagreements/4ad0927e-4eb2-####-####-############",
"stepUp": {
"type": "CAPTURE_CVV",
"mandatory": true,
"url": "https://iframe.environment.payments.woolworths.com.au/container-ws/getCaptureFrame/cvv/5c4601d4-92ec-####-####-############/213###",
"sessionId": "5c4601d4-92ec-####-####-############"
}
}
],
"googlePay": {
"paymentInstrumentId": "226####",
"paymentToken": "f0a75614-3c67-####-####-############",
"status": "VERIFIED",
"createdOn": "2022-03-28T16:25:22.993+11:00",
"lastUpdated": "2022-03-28T16:25:25.448+11:00",
"lastUsed": "2022-03-28T16:25:23.448+11:00",
"primary": false,
"allowed": true,
"expired": true,
"stepUp": {
"type": "REFRESH_TOKEN",
"mandatory": true,
"url": "https://environment.woolworths.com.au/wow/v1/pay/googlepay/tokenize/f0a75614-3c67-####-####-############"
}
},
"applePay": {
"paymentInstrumentId": "217####",
"paymentToken": "c87bb55e-2c2b-####-####-############",
"status": "VERIFIED",
"createdOn": "2022-02-22T11:40:56.815+11:00",
"lastUpdated": "2022-03-07T14:21:57.969+11:00",
"lastUsed": "2022-03-07T14:21:58.530+11:00",
"primary": false,
"allowed": true,
"stepUp": {
"type": null,
"mandatory": true,
"url": "https://environment.woolworths.com.au/wow/v1/pay/applepay/tokenize/217####"
}
}
},
"meta": {}
}
Where:
paymentInstrumentIdis the payment token of the associated instrument saved in the customer's walletpaymentTokenis the payment token unique GUID of the associated instrument saved in the customer's walletstatusis 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.lastUpdatedis the date the instruments information was last updated.lastUsedis the date the instrument was last used to make a payment.allowedindicates whether the instrument is an allowed payment method based on your merchant config with Wpay.schemeindicates the issuer scheme of the tokenized card.cardSuffixprovides the last 4 digits of the tokenized credit card for display purposes.cardNameis the name given to the card at the point of tokenization.expiryMonthindicates the month to which the card will be valid. This is indicated as a 2 digit MM field.expiryYearindicates the year in which the card expires. This is indicated as a 2 digit YY field.cvvValidatedexpiredindicates if the card has expired based on the cards expiry month and year as compared to the current date.requiresCVVindicates if the CVV is required when making a payment utilizing the saved card. This is based on your merchant preferences with Wpay. Where this is true a step up token will need to be provided during payment. See Step Up ProcessstepUp: mandatorywill align with the requiresCVV indicator.
List Instruments including Gift Card Balance
You can also include an optional include=GC_BALANCE parameter when calling Get Payment Instruments List to retrieve all saved payment instruments and get the gift card balance at the same time. Refer to Retrieve Gift Card Balance using List Instruments.
Retrieve a Gift Card
In some circumstances, you may want to retrieve your registered customers gift card from their wallet. Provided you already know the paymentInstrumentId from List Instrument API, you may call the API below to retrieve the gift card information securely.
curl --location --request GET 'https://{{environment}}.wpay.com.au/wow/v1/pay/instore/customer/instruments/{{paymentInstrumentId}}?publicKey={{uriEncodedPublicKey}}&algo=(rsa|ec)' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}'
var myHeaders = new Headers();
var environment = "substitute environment-value here";
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
var uriEncodedPublicKey = "enter your public key";
var algo = "select either rsa or ecc"
var paymentInstrumentId = "enter giftcard payInstrument Id here";
myHeaders.append("accept", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch(`https://${environment}.wpay.com.au/wow/v1/pay/instore/customer/instruments/${paymentInstrumentId}?publicKey=${uriEncodedPublicKey}&algo=${algo}`, 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 uriEncodedPublicKey = "enter your public key"
let algo = "rsa / ecc"
let paymentInstrumentId = "enter giftcard payInstrument Id here"
let request = URLRequest(url: URL(string: "https://\(environment).wpay.com.au/wow/v1/pay/instore/customer/instruments/\(paymentInstrumentId)?publicKey=\(uriEncodedPublicKey)&algo=\(algo)")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "accept")
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 yourAPIkey = "YOUR-API-KEY"
var environment = "substitute environment-value here"
var accessToken = "ACCESS-TOKEN"
var uriEncodedPublicKey = "enter your public key"
var algo = "rsa / ecc"
var paymentInstrumentId = "enter giftcard payInstrument Id here"
val response = khttp.get(
url = "https://$environment" +
".wpay.com.au/wow/v1/pay/instore/customer/instruments/$paymentInstrumentId?" +
"publicKey=$uriEncodedPublicKey&algo=$algo",
headers = mapOf("Content-Type" to "application/json",
"X-Api-Key" to yourAPIkey,
"Authorization", "Bearer $accessToken")
)
if(response.statusCode == 200) {
val obj : JSONObject = response.jsonObject
println("""Successful response payload: ${obj["data"]}""")
} else {
handleError(response)
}
Where
uriEncodedPublicKeyquery parameter is the RSA / ECC public keyalgoquery parameter is either set torsafor RSA encryption orecfor ECC encryption.paymentInstrumentIdis the tokenized payment instrument of the gift card. This can be derived the list payment instruments response.
Gift Card Retrieval Encryption
To retrieve gift card number and pin securely, you must generate either an RSA (Rivest-Shamir-Adleman) or ECC (Elliptic Curve Cryptography) public and private keys on your server and embed the public key into the request query parameter. The key pair must remain valid either for the duration of the customer session or for one-time use in a single request / response cycle. Provided the gift card can be found in the customers wallet, you may then decrypt the response with the private key to extract the gift card number and pin.
Transaction Outcome
{
"data": {
"paymentInstrumentId": "81xxx",
"paymentInstrumentType": "GIFT_CARD",
"paymentToken": "ec9b****-****-****-****-a8ca4f*******",
"status": "UNVERIFIED_PERSISTENT",
"createdOn": "2017-11-06T08:38:09.890Z",
"lastUpdated": "2017-11-06T19:38:09.860+11:00",
"lastUsed": "2017-10-12T13:25:49.770+11:00",
"primary": true,
"allowed": true,
"paymentInstrumentDetail": {
"cardSuffix": "2517",
"programName": "WISH Gift Card"
}
},
"meta": {
"cipherText": "INLh2cH2MtnTKQ1RxwwWQHiXUZ**********************"
}
}
Where
cipherTextis encrypted and base64 encoded gift card data. You will need to decrypt and decode it (using base64 encoding) in order to extract the gift card number and pin.paymentInstrumentIdis the payment token of the associated gift card saved in the customer's wallet.paymentTokenis the payment token unique GUID of the associated gift card saved in the customer's walletstatusis 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.lastUpdatedis the date the gift card information was last updated.lastUsedis the date the gift card was last used to make a payment.allowedindicates whether the gift card is an allowed payment method based on your merchant config with Wpay.cardSuffixprovides the last 4 digits of the tokenized gift card for display purposes.programNameis the gift card name given at the point of tokenization.
Sample of the gift card number and pin after decryption can be seen below.
plainText={
"pinCode" : "3333",
"cardNumber" : "628759191************"
}
Updated over 1 year ago