Tokenizing Apple Pay

To tokenize an Apple Pay instrument and use it to make a payment or store it in the customer's Wpay wallet, we will first need to set up your merchant profile. To tokenize a customer's Apple Pay instrument you can make use of our APIs.

📘

Apple Pay on the Web (Safari)

For Apple Pay on the web, you will use Wpay Apple Pay certificate that we can configure against your merchant's profile in our system.

High-level flow - Web

2878

How it works

  1. Integrate your websites with Apple Pay to facilitate the checkout journey and allow a customer to select an instrument stored in their Apple Pay account.
  2. Get a paymentsession object from Wpay to create and encrypt payment data (since you will be using Wpay Apple Pay certificate).
  3. Once the user authorises the payment using Touch ID / Face ID, send the encrypted payment data to Apple servers, where it is re-encrypted using Wpay Payment Processing certificate and receive back a PaymentToken from Apple.
  4. This PaymentToken can then be provided to Wpay to be decrypted in our secure environment for tokenization. Please see the Payment Token Format for more information.
  5. The Apple Pay data is processed by us during tokenization and we return a Wpay PaymentToken which is a unique representation of the Apple Pay instrument without any sensitive information.
  6. The Wpay PaymentToken can be used in our payments services to make a payment.

📘

Apple Pay on Mobile Apps

For Apple Pay on Mobile Apps you will need to first provide us with your Apple Pay account information so that we can link this to your Wpay account.

High level flow - iOS App

2925

How it works

  1. Integrate your iOS app with Apple Pay to facilitate the checkout journey and allow a customer to select an instrument stored in their Apple Pay account.
  2. Get a paymentsession object from Apple using your own Apple Pay certificate to create and encrypt payment data.
  3. Once the user authorises the payment using Touch ID / Face ID, send the encrypted payment data. to Apple servers, where it is re-encrypted using your Payment Processing certificate and receive back a PaymentToken from Apple.
  4. This PaymentToken can then be provided to Wpay to be decrypted in our secure environment for tokenization. Please see the Payment Token Format for more information.
  5. The Apple Pay data is processed by us during tokenization and we return a Wpay PaymentToken which is a unique representation of the Apple Pay instrument without any sensitive information.
  6. The Wpay PaymentToken can be used in our payments services to make a payment.

Tokenizing Apple Pay

This method should be used to tokenize Apple Pay payment token data. The same API can be used for registered and guest customers.

curl --location --request POST 'https://{{environment}}.wpay.com.au/v1/apm/tokenize' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: {{yourApiKey}}' \
--header 'Authorization: Bearer {{yourBearerToken}}' \
--data-raw '{
    "data": {
        "paymentInstrumentType": "APPLEPAY",
        "payload": {
            "data": "a15owFtc***********************",
            "ephemeralPublicKey": "MFkwEwY**********************************",
            "publicKeyHash": "AwqjNE********************************",
            "transactionId": "87a124b**********************",
            "signature": "MIAGCSq********************************",
            "version": "EC_V1",
            "instrumentType": "AMEX",
            "primary": true,
            "comment": "AMEX-0001",
            "applicationData":"3B4893D8B********************************************"
        }
    },
    "meta": {}
}'
var myHeaders = new Headers();
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);

var raw = JSON.stringify({
  "data": {
        "paymentInstrumentType": "APPLEPAY",
        "payload": {
            "data": "a15owFtc***********************",
            "ephemeralPublicKey": "MFkwEwY**********************************",
            "publicKeyHash": "AwqjNE********************************",
            "transactionId": "87a124b**********************",
            "signature": "MIAGCSq********************************",
            "version": "EC_V1",
            "instrumentType": "AMEX",
            "primary": true,
            "comment": "AMEX-0001",
            "applicationData":"3B4893D8B********************************************"
        }
    },
    "meta": {}
});

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

fetch(`https://${environment}.wpay.com.au/v1/apm/tokenize`, 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 = """
{\
	\"data\": {\
		\"paymentInstrumentType\": \"APPLEPAY\",\
		\"payload\": {\
				\"data\": \"a15owFtc***********************\",\
				\"ephemeralPublicKey\": \"MFkwEwY**********************************\",\
				\"publicKeyHash\": \"AwqjNE********************************\",\
				\"transactionId\": \"87a124b**********************\",\
				\"signature\": \"MIAGCSq********************************\",\
				\"version\": \"EC_V1\",\
				\"instrumentType\": \"AMEX\",\
				\"primary\": true,\
				\"instrumentType\": \"AMEX\",\
				\"comment\": \"AMEX-0001\",\
				\"applicationData\": \"3B4893D8B********************************************\"\
		}\
	},\
	\"meta\": {}\
}\
"""

let postData = parameters.data(using: .utf8)

var request = URLRequest(
  url: URL(string: "https://\(environment).wpay.com.au/v1/apm/tokenize")!,
  timeoutInterval: Double.infinity
)
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()

Where:

  • paymentInstrumentType should be set to APPLEPAY for Apple Pay tokenization.
  • data within payload can be retrieved from the decrypted PaymentToken from Apple. This contains encrypted payment data.
  • ephemeralPublicKey can be retrieved from the decrypted PaymentToken from Apple. This is an Ephemeral public key bytes.
  • publicKeyHash can be retrieved from the decrypted PaymentToken from Apple. This is a hash of the encoded public key of your merchant’s certificate.
  • transactionId can be retrieved from the decrypted PaymentToken from Apple. This is a transaction identifier that is generated on the device.
  • signature can be retrieved from the decrypted PaymentToken from Apple. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.
  • version can be retrieved from the decrypted PaymentToken from Apple. The token uses EC_V1 for ECC-encrypted data, and RSA_V1 for RSA-encrypted data.
  • instrumentType is the payment network of the card selected.
  • primary can be set to true or false and this indicates whether it is a primary or secondary instrument when saving the card to the customer's wallet.
  • comment is the display name of the card selected, generally, this is the payment network following by the last 4 digits of the selected card.
  • applicationData can be retrieved from PaymentToken from Apple. This field contains application-specific data or state.

Sample Tokenization Response

{
  "data": {
    "paymentInstrumentId": "2484***",
    "allowed": true,
    "status": "VERIFIED",
    "paymentInstrumentType": "APPLE_PAY",
    "paymentToken": "2f3ddc79-****-****-****-************",
    "stepUpToken": "e80c40fe-****-****-****-************"
  },
  "meta": {}
}

Where:

  • paymentInstrumentId is the new payment instrument id to be used for payments.
  • allowed is a flag to indicate if the merchant profile in the container is allowed to use this payment instrument.
  • status indicates the status of the payment instrument in the container.
  • paymentInstrumentType is the type of instrument for which token has been generated. For Apple Pay, this value will be set to APPLE_PAY.
  • paymentToken is the Apple pay payment token. Payment token is a unique identifier for the payment instrument.
  • stepUpToken is the step-up token to be used for payments.