Apple Pay is a mobile payment and digital wallet service by Apple Inc. that allows payers to make payments with supported iOS and macOS devices. Apple Pay is a supported device payment in the Mastercard Payment Gateway.
This page describes integration details specific to Apple Pay. It's recommended that you read the integration guidelines for device payments, before building your Apple Pay integration.
To accept Apple Pay payments:
You can integrate Apple Pay into your mobile app or the checkout page of your website using Direct Payment.
If you want to decrypt the payment token on your server, see Decrypting the Payment Token.
order.walletProvider
=APPLE_PAY
order.amount
: The value you provide must be the final amount of the order (including shipping and other additional amounts).order.currency
sourceOfFunds.provided.card.devicePayment.paymentToken
: The encrypted payment token obtained from the Apple Pay SDK. For example, the value in PKPaymentToken.paymentData
sourceOfFunds.provided.card.devicePayment.paymentToken [REST][NVP]
In addition to the standard fields, the following response fields are returned for a successful authorization using the payment token.
sourceOfFunds.provided.card.encryption
=DEVICE
sourceOfFunds.provided.card.deviceSpecificNumber
: The DPAN in masked format.sourceOfFunds.provided.card.deviceSpecificExpiry.month
sourceOfFunds.provided.card.deviceSpecificExpiry.year
sourceOfFunds.provided.card.number
: The FPAN in masked format.sourceOfFunds.provided.card.expiry.month
: The expiry month of the card.sourceOfFunds.provided.card.expiry.year
: The expiry year of the card.sourceOfFunds.provided.card.devicePayment.cryptogramFormat
Here's a sample Authorization Request in REST where payment token is decrypted by the gateway.
{ "apiOperation": "AUTHORIZE", "order": { "currency": "USD", "amount": "61.00", "walletProvider": "APPLE_PAY" }, "sourceOfFunds": { "type": "CARD", "provided":{ "card":{ "devicePayment":{ "paymentToken":"{\r\n\t\"version\": \"EC_v1\",\r\n\t\"data\":\"WO\/fTbdARsB1Rg3tS4ISwNG4cWDRk3JZDSbP32iDdeMP7UFouS...\", \r\n\t\"signature\": \"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkg...\", \r\n\t\"header\": {\r\n\t\t\"transactionId\": \"c162557e7ae1c69a47583bc2364d1a3e531428d13fb664032f9e09fa37381fc1\", \r\n\t\t\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMeuRqVEOZAQ...\", \r\n\t\t\"publicKeyHash\": \"tBGp1mEoHLiHwfOkazpKVbf3cMKmVS98PGufUJ2Q3ys=\"\r\n\t}\r\n}" //This is only a sample token and will not pass validation. You should substitute this with an actual payment token returned from Apple Pay (PKPaymentToken.paymentData). //The gateway considers this value to be a string, NOT JSON itself. The parenthesis are a part of the string. } } } }, "transaction": { "source": "INTERNET" } }
{ "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0314", "financialNetworkCode": "MCC", "posData": "1025104006600", "posEntryMode": "812", "processingCode": "003000", "responseCode": "00", "stan": "46465", "time": "101534", "transactionIdentifier": "447345902", "transactionIntegrityClass": "A1" }, "device": { "ani": "12341234" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTMERCHANT", "order": { "amount": 30.10, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2023-03-14T10:15:33.819Z", "currency": "USD", "id": "844205983", "lastUpdatedTime": "2023-03-14T10:15:34.265Z", "merchantAmount": 30.10, "merchantCategoryCode": "1234", "merchantCurrency": "USD", "status": "AUTHORIZED", "totalAuthorizedAmount": 30.10, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00, "walletProvider": "APPLE_PAY" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "devicePayment": { "cryptogramFormat": "3DSECURE" }, "deviceSpecificExpiry": { "month": "1", "year": "39" }, "deviceSpecificNumber": "512345xxxxxx0008", "fundingMethod": "UNKNOWN", "number": "xxxxxxxxxxxxxxxx", "scheme": "MASTERCARD", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2023-03-14T10:15:34.265Z", "timeOfRecord": "2023-03-14T10:15:33.930Z", "transaction": { "acquirer": { "batch": 20230314, "date": "0314", "id": "SYSTEST_ACQ_S2I", "merchantId": "12345678", "transactionId": "447345902" }, "amount": 30.10, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "USD", "id": "950596203", "receipt": "307310046465", "source": "INTERNET", "stan": "46465", "terminal": "1111", "type": "AUTHORIZATION" }, "version": "71" }
You can choose to decrypt the payment token on your server instead of providing the payment token for decryption to the gateway. In this case, you will need to take responsibility for storing the encryption credentials and executing the decryption.
Apple Pay JSON Key |
Corresponding API Request Field |
Description |
---|---|---|
applicationPrimaryAccountNumber | sourceOfFunds.provided.card.number | The device-specific primary account number (i.e., token or DPAN) of the card that funds this transaction. |
applicationExpirationDate | sourceOfFunds.provided.card.expiry.month sourceOfFunds.provided.card.expiry.year |
The expiration date of the applicationPrimaryAccountNumber. |
cardholderName | sourceOfFunds.provided.card.nameOnCard | (Optional)The cardholder's name. |
currencyCode | order.currency | The ISO 4217 currency code for the transaction. |
transactionAmount | order.amount | The order amount. |
paymentDataType | sourceOfFunds.provided.card. devicePayment.cryptogramFormat |
The cryptogram format. Set this to 3DSECURE. |
onlinePaymentCryptogram | sourceOfFunds.provided.card.devicePayment. onlinePaymentCryptogram |
Cryptogram in 3DSecure format. |
eciIndicator | sourceOfFunds.provided.card.devicePayment. eciIndicator |
Provide the electronic commerce indicator (ECI), if available. |
PAYER_TERMINAL_OFF_PREMISES
or PAYER_TERMINAL_ON_PREMISES
. If you do not provide a value, PAYER_TERMINAL_OFF_PREMISES
is used.Here's a sample Authorization Request in REST where the values from the decrypted payment token are provided to the gateway.
{ "apiOperation": "AUTHORIZE", "order": { "amount": "30.10", "currency": "USD", "walletProvider":"APPLE_PAY" }, "sourceOfFunds": { "provided": { "card": { "expiry": { "month": "01", "year": "39" }, "number": "5123450000000008", "devicePayment":{ "cryptogramFormat":"3DSECURE", :{ "onlinePaymentCryptogram":"IA/8pdiWftSsxpFT6wABoDABhgA=", "eciIndicator":"20" } } } }, "type": "CARD" }, "device": { "ani":"12341234" }, "transaction": { "source": "INTERNET" } }
{ "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0329", "financialNetworkCode": "MCC", "posData": "1025104006600", "posEntryMode": "812", "processingCode": "003000", "responseCode": "00", "stan": "287916", "time": "005723", "transactionIdentifier": "260113124", "transactionIntegrityClass": "A1" }, "device": { "ani": "12341234" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TEST_MERCHANT", "order": { "amount": 30.1, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "ESTIMATED", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2022-03-29T00:57:22.553Z", "currency": "USD", "id": "C999903", "lastUpdatedTime": "2022-03-29T00:57:23.813Z", "merchantAmount": 30.1, "merchantCategoryCode": "1234", "merchantCurrency": "USD", "status": "AUTHORIZED", "totalAuthorizedAmount": 30.1, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0, "walletProvider": "APPLE_PAY" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "devicePayment": { "cryptogramFormat": "3DSECURE" }, "deviceSpecificExpiry": { "month": "1", "year": "39" }, "deviceSpecificNumber": "512345xxxxxx0008", "fundingMethod": "UNKNOWN", "number": "xxxxxxxxxxxxxxxx", "scheme": "MASTERCARD", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-03-29T00:57:23.813Z", "timeOfRecord": "2022-03-29T00:57:22.675Z", "transaction": { "acquirer": { "batch": 20220329, "date": "0329", "id": "TESTACQUIRER", "merchantId": "123463", "transactionId": "260113124" }, "amount": 30.1, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "USD", "id": "1", "receipt": "208800287916", "source": "INTERNET", "stan": "287916", "terminal": "12333", "type": "AUTHORIZATION" }, "version": "71" }
You can test your integration with the gateway in production using your test merchant profile and a supported FPAN as provided by Apple for sandbox testing.
You must configure your app to use Apple Pay sandbox environment with your gateway test merchant profile. When the payer selects a card in Apple Pay, the app generates a payment token in test mode.
If you are decrypting the payment token, use the DPAN from the decrypted token to perform test transactions.
If gateway decrypts the payment token, you must procure a signed certificate from Apple and upload it to the gateway via Merchant Administration in production using your gateway test merchant profile. The gateway uses the certificate to decrypt the payment token.
If the transactions are either APPROVED or DECLINED then the gateway was able to process your test transactions successfully.
The Mobile SDK assists you to develop a mobile application (app) that will accept digital payments via the Mastercard Payment Gateway. The gateway offers support for Apple Pay via the Mobile SDK. Click here for the Mobile SDK integration guidelines for the iOS platform.
Copyright © 2023 Mastercard