1. Integrate Apple Pay API and Payment button

You will need to set up Apple pay before requesting Apple Pay tokens.

Apple Pay payment button implementation

📘
When you have completed the Apple Pay set up and request a payment, integrate the Apple Pay button according to the Apple brand guidelines on your checkout page to collect cards stored in the Apple wallet.

2. Convert Apple Pay tokens into PCI Proxy aliases

Look for the ApplePayPaymentToken object. You will find it in the ApplePayPaymentAuthorizedEvent object in the onpaymentauthorized event handler of the Apple Pay API. It contains the encrypted Apple Pay token and is called after the cardholder has authorized the Apple Pay payment with Touch ID, Face ID or a passcode.

Submit the Apple Pay token to the PCI Proxy Vault endpoint to convert the Apple Pay token into a PCI Proxy token.

curl --request POST \
  --url https://api.sandbox.datatrans.com/v1/aliases/tokenize \
  --header 'Authorization: Basic {{basicAuth}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"requests": [
		{
			"type": "APPLE_PAY",
			"token": "{\"data\":\"xbvylStxG+RF5i1YukbZxhcKa4UIxkDCQed/hdfEnhptSkiSZcPeth8CcuxR2cU2xS2DPtO+sCKx5meY9cprZLsMNTu8YQ7ebPGBw43E07+BLjQc/0xeY09gMEqn50MsIjgDaSD4q/LjXtNNFsmB3nMBy4elNlo4AbS6ifqzpkVT6O3SPfg3iwih8DfTbbSIHcnfumPdb4p6I79cui9reMBjR6wD80GJT6VXi/FxkhoMkWbdFCxQFhn99fzCYBj/dSdZ/x8n3qITfg7m8FShJlxObtraNb8MRrfyW9jysIHrZI4OuEGc/X5DGEjlJUvoZSyatr151tRQp5SqQiKSV874b3o9ZMsMC6TlUaqJ22hpRzqddZbnD3S1gXs/i5r/1VCDOZjQXNdK3D2kS6MB9sU4MvJ64RcImj535HaZIQ==\",\"signature\":\"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\",\"header\":{\"publicKeyHash\":\"b9zDmQ+FYzEZJw9+q8idpA8fPtsSJ5+OpGiQDhCISQ0=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGZBfM5CWPdoTLorTKtVQDEeSu9bVdyxcYt0aAzR4HObZMqT98XlISVy2qjbg7Sq3kVLTHmhuIa6LW1nhyvy8PA==\",\"transactionId\":\"b1609bb088bd2995e043fcc2aeb6efad5545e55476bd933d0f3d75c1bfff7903\"},\"version\":\"EC_v1\"}"
		}
	]
}'

{
	"overview": {
		"total": 1,
		"successful": 1,
		"failed": 0
	},
	"responses": [
		{
			"type": "CARD",
			"alias": "7LHXscqwAAEAAAGEiwgfM8CBTPrzACwH",
			"maskedCC": "489537xxxxxx6287",
			"fingerprint": "F-fgxnFwN-gsIw7y80T-kpBB"
		}
	]
}

3. Obtain card metadata and 3D information

Finally, use the alias and call the Token Status API to obtain the card metadata and 3D Secure related information.

Check the walletIndicator parameter to see the original wallet provider of the returned token. For Apple Pay, it returns APL.

Strong customer authentication and liability shift

📘
Visa Apple Pay tokens come with inbuilt 3D Secure data such as caav and the eci value. For Mastercard tokens the eci value is not available.
If you're using the multiTokenContexts in the Apple Pay request, the different authentication values are returned in the 3D object of the Alias status response. See an example in the Response multiToken tab below.
We still recommend you to check with your payment provider directly to find out if Apple Pay transactions grant liability shift by default, as this can vary based on issuer country and card scheme brand.

Example

curl --request GET \
  --url https://api.sandbox.datatrans.com/v1/aliases/7LHXscqwAAEAAAGHLZMxjcu65Ep6AAhH \
  --header 'Authorization: {merchantId}:{password}' \
  --header 'Content-Type: application/json'

{
    "alias": "-E2Jd7_gAAEAAAGKuCoxG0AvLPB-AH8d",
    "fingerprint": "F-fmjpZO8Nv7FK2kNOO9XPPp",
    "type": "CARD",
    "masked": "489537xxxxxx6287",
    "dateCreated": "2023-05-21T14:34:47Z",
    "card": {
        "panRemoved": false,
        "expiryMonth": "06",
        "expiryYear": "25",
        "cardInfo": {
            "brand": "VISA CREDIT",
            "type": "credit",
            "usage": "consumer",
            "country": "GB",
            "issuer": "DATATRANS",
            "accountType": "TOKEN"
        },
        "3D": {
            "cavv": "/wAAAAABQpFnQqQEs/JQgQhgAgA=",
            "eci": "5"
        },
        "walletIndicator": "APL"
    }
}

{
    "alias": "7LHXscqwAAEAAAGRl_Fm1B7U3ggxAJ_w",
    "fingerprint": "F-fRDgs-P2oomsUqABNSKqFq",
    "type": "CARD",
    "masked": "412374xxxxxx0013",
    "dateCreated": "2023-08-28T07:44:25Z",
    "card": {
        "usage": "SIMPLE",
        "expiryMonth": "06",
        "expiryYear": "25",
        "last4": "0013",
        "panRemoved": false,
        "cardInfo": {
            "brand": "VISA",
            "type": "credit",
            "usage": "consumer",
            "country": "US",
            "issuer": ""
        },
        "walletIndicator": "APL",
        "3D": {
            "eci": "7",
            "multiToken": [
                {
                    "cavv": "YwAAAAEAKaKT+ywF21wcgOhgEwA=",
                    "merchantIdentifier": "6754e10dabc367773adf38d948549771664cccd379430aa0cc3b0d9f2c8074b0",
                    "amount": 100
                },
                {
                    "cavv": "YwAAAAIAMy1+rVkF21wcgOhgEwA=",
                    "merchantIdentifier": "6754e10dabc367773adf38d948549771664cccd379430aa0cc3b0d9f2c8074b0",
                    "amount": 200
                }
            ]
        }
    }
}

📘
Apple Pay only returns a tokenized device PAN (DPAN) and never the actual funding PAN (FPAN).
Hence, the values returned in the propertiesmasked, expiryMonth and expiryYear are based on the device pan (DPAN) and not the funding pan (FPAN). However, card meta information in the cardInfo object are based on the FPAN value.
To see the last 4 digits of the FPAN please check the response from the Apple API directly.

Testing your integration

Check out https://paymentbutton.datatrans.dev/ to see an example and test out the Apple Pay integration. Note that it only works with the Safari browser.

❗️
Make sure to toggle Output Token Data and ignore the rest of the options available.