Device Payments Integration

Apple Pay Payments

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.

Prerequisites

To accept Apple Pay payments:

You must sign up with Apple and create your merchant ID.
Your merchant profile on the gateway must be enabled for Device Payments by your payment service provider.
If you want the gateway to perform the decryption of the payment token, your merchant profile on the gateway must have "Enable Decryption of Apple Pay Device Payments" permission.

Adding Support for Apple Pay to your Integration

You can integrate Apple Pay into your mobile app or the checkout page of your website using Direct Payment.

Gateway support for decrypting Apple Pay payment token is available from API version 46 onwards.

Procure a signed certificate from Apple and upload to the gateway via Merchant Administration.

If you want to decrypt the payment token on your server, see Decrypting the Payment Token.
On payment confirmation, provide the following fields in the Authorize/Pay or an Update Session request.
- 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]
The gateway will decrypt the payment token for you and process the transaction using the decrypted data.

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

Example Request

Here's a sample Authorization Request in REST where payment token is decrypted by the gateway.

URL	https://na.gateway.mastercard.com/api/rest/version/70/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method	PUT

  {
    "apiOperation": "AUTHORIZE",
     "order": {
        "currency": "EUR",
        "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"
    }
}

Example Response

  {
    "authorizationResponse": {
        "date": "0327",
        "posData": "1025104006600",
        "posEntryMode": "812",
        "processingCode": "003000",
        "responseCode": "49",
        "stan": "297295",
        "time": "235040"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "TEST_MERCHANT",
    "order": {
        "amount": 30.1,
        "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
        "certainty": "ESTIMATED",
        "chargeback": {
            "amount": 0,
            "currency": "EUR"
        },
        "creationTime": "2022-03-27T23:50:40.162Z",
        "currency": "EUR",
        "id": "01",
        "lastUpdatedTime": "2022-03-27T23:50:40.650Z",
        "merchantAmount": 100,
        "merchantCategoryCode": "1234",
        "merchantCurrency": "EUR",
        "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": "9",
                    "year": "22"
                },
                "deviceSpecificNumber": "520424xxxxxx6937",
                "encryption": "DEVICE",
                "fundingMethod": "UNKNOWN",
                "number": "xxxxxxxxxxxxxxxx",
                "scheme": "MASTERCARD",
                "storedOnFile": "NOT_STORED"
            }
        },
        "type": "CARD"
    },
    "timeOfLastUpdate": "2022-03-27T23:50:40.650Z",
    "timeOfRecord": "2022-03-27T23:50:40.282Z",
    "transaction": {
        "acquirer": {
            "id": "TESTACQUIRER",
            "merchantId": "123463"
        },
        "amount": 30.1,
        "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
        "currency": "EUR",
        "id": "1",
        "receipt": "208623297295",
        "source": "INTERNET",
        "stan": "297295",
        "terminal": "12333",
        "type": "AUTHORIZATION"
    },
    "version": "64"
}

Decrypting the Payment Token

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.

Support for Apple Pay with merchant-managed decryption of payment token is available from API version 40 onwards.

On payment confirmation, submit the encrypted payment token returned by Apple Pay to your server.
Decrypt the payment token on your server using your private key. See decryption steps here.

Provide the payment data keys from the decrypted token in the corresponding transaction fields on the Authorize/Pay request or the Update Session request.

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. 3DSecure.onlinePaymentCryptogram	Cryptogram in 3DSecure format.
eciIndicator	sourceOfFunds.provided.card.devicePayment. 3DSecure.eciIndicator	Provide the electronic commerce indicator (ECI), if available.

sourceOfFunds.provided.card.devicePayment [REST][NVP]

In addition to the above fields, include these in the Authorize/Pay or Update Session request and submit it to the gateway.
- transaction.source=INTERNET
- order.walletProvider=APPLE_PAY
- device.mobilePhoneModel: (optional) The identifier of the mobile device used to initiate the payment.
- posTerminal.location: You can specify PAYER_TERMINAL_OFF_PREMISES or PAYER_TERMINAL_ON_PREMISES. If you do not provide a value, PAYER_TERMINAL_OFF_PREMISES is used.

Example Request

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",
                    "3DSecure":{
                        "onlinePaymentCryptogram":"IA/8pdiWftSsxpFT6wABoDABhgA=",
                        "eciIndicator":"20"
                    }
                }
            }
            
        },
        "type": "CARD"
    },
    "device": {
        "ani":"12341234"
    },
    "transaction": {
               "source": "INTERNET"
    } 
}

Example Response

  {
    "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": "64"
}

Testing Apple Pay Integration

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.

Apple Pay via Mobile SDK

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.