# Apple Pay source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/apple-pay/index.md 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 digital wallet in the Mastercard Gateway. This topic includes step-by-step integration steps for Apple Pay. For more information about digital wallets and their payment flow, see [Digital Wallets](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/index.md). Warning: Apple Pay is supported from API version 40 and later. These Integration methods are supported. | Integration methods | Payment methods | Operations | Card brands supported | |------------------------------------|----------------------------|------------------------------------|--------------------------------------------| | * Direct Payment * Hosted Checkout | * Credit card * Debit card | * AUTHORIZE * PAY * UPDATE SESSION | * Mastercard * VISA * AMEX * MADA * Jaywan | To view examples of API requests for digital wallet payments, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). ## Prerequisites {#prerequisites} To accept Apple Pay payments: * Sign up with Apple and create your merchant ID. See steps to sign up with Apple and create a Merchant ID [here](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/applying-to-use-the-registration-api-and-configuring-ids). * Your merchant profile must be enabled by your payment service provider on the gateway for device payments. * If you want the gateway to perform the decryption of the payment token, your merchant profile on the gateway must have the "Enable Apple Pay on Hosted Checkout" and "Enable Gateway-Managed Apple Pay on the web payments" privileges required for [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-checkout/integrate-apple-pay-in-hosted-checkout/index.md) integration method. ## Adding support for Apple Pay to your integration {#adding-support-for-apple-pay-to-your-integration} You can integrate Apple Pay into your mobile app or the checkout page of your web site using the [direct payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md) integration method. Warning: Gateway support for decrypting Apple Pay payment tokens is available from API version 46 and later.
1. Procure a signed certificate from Apple and upload it to the gateway in the Merchant Administration. If you want to decrypt the payment token on your server, see [Decrypting the Payment Token](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/apple-pay/index.md#decrypting-the-payment-token). 2. On payment confirmation, provide the following fields in the [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction), [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction), or [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request. * `order.walletProvider = APPLE_PAY` Apple Pay digital wallet provider * `order.amount` Total amount for the order. The value you provide must be the final amount of the order including shipping and other additional amounts. * `order.currency` Currency of the order * `sourceOfFunds.provided.card.devicePayment.paymentToken` Encrypted payment token obtained from the Apple Pay SDK. For example, the value in `PKPaymentToken.paymentData`. ### AUTHORIZE request example for decryption in gateway {#authorize-request-example-for-decryption-in-gateway} ```json { "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 parentheses are a part of the string. } } } }, "transaction": { "source": "INTERNET" } } ``` The gateway decrypts the payment token for you and processes 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, if the issuer successfully maps the Device Primary Account Number (DPAN) to the Funding Primary Account Number (FPAN): * `sourceOfFunds.provided.card.encryption = DEVICE` Encrypted by a payer's device such as a mobile phone. * `sourceOfFunds.provided.card.deviceSpecificNumber` 6.4 masked DPAN. * `sourceOfFunds.provided.card.deviceSpecificExpiry.month` Expiry month of the DPAN. * `sourceOfFunds.provided.card.deviceSpecificExpiry.year` Expiry year of the DPAN. * `sourceOfFunds.provided.card.number` Masked FPAN, usually 0.4 masked, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.month` Expiry month of the FPAN, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.year` Expiry year of the FPAN, were available from the acquirer. * `sourceOfFunds.provided.card.devicePayment.cryptogramFormat` Format of the cryptogram provided for the digital wallet payment. If you request for an unmasked PAN to be returned in the transaction response, the gateway returns an unmasked DPAN and FPAN, depending on the acquirer support. Warning: If you want to return unmasked card numbers, you must have the requisite privilege, set the `responseControls.sensitiveData` field to UNMASK, and authenticate your call to the API using certificate authentication. ### AUTHORIZE response example {#authorize-response-example} ```json { "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", "encryption": "DEVICE", "expiry": { "month": "11", "year": "27" }, "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" } ``` ### Decrypting the payment token {#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 must store the encryption credentials and execute the decryption. 1. On payment confirmation, submit the encrypted payment token returned by Apple Pay to your server. 2. Decrypt the payment token on your server using your private key. For information on the decryption steps, see [Payment token format reference](https://developer.apple.com/documentation/passkit/payment-token-format-reference#//apple_ref/doc/uid/TP40014929). 3. Provide the payment data keys from the decrypted token in the corresponding transaction fields in the AUTHORIZE, PAY, or UPDATE SESSION request. Table: Payment data keys and the corresponding API request fields | Apple Pay JSON Key | Corresponding API Request Field | Description | |---------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------------| | applicationPrimaryAccountNumber | sourceOfFunds.provided.card.number | DPAN of the card that funds this transaction | | applicationExpirationDate | sourceOfFunds.provided.card.expiry.month sourceOfFunds.provided.card.expiry.year | Expiration date of the applicationPrimaryAccountNumber | | cardholderName | sourceOfFunds.provided.card.nameOnCard | cardholder's name (optional) | | currencyCode | order.currency | ISO 4217 currency code for the transaction | | transactionAmount | order.amount | Order amount | | paymentDataType | sourceOfFunds.provided.card.devicePayment.cryptogramFormat | Cryptogram format. Set this to EMV 3-D Secure | | onlinePaymentCryptogram | sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram | Cryptogram in EMV 3-D Secure format | | eciIndicator | sourceOfFunds.provided.card.devicePayment.eciIndicator | Electronic Commerce Indicator (ECI), if available | 4. In addition to the Payment data keys and the corresponding API request fields, provide the following fields in the AUTHORIZE, PAY, or UPDATE SESSION request and submit it to the gateway: * `transaction.source = INTERNET` Channel through which you received authorization for the payment for this order. Value INTERNET indicates that the payer initiated the payment online. * `order.walletProvider = APPLE_PAY` Apple Pay digital wallet provider. * `device.mobilePhoneModel(optional)` Identifier of the mobile device used to initiate the payment. * `posTerminal.location` Physical location of the device in relation to your business premises. The possible values are PAYER_TERMINAL_OFF_PREMISES or PAYER_TERMINAL_ON_PREMISES.If you do not provide a value, PAYER_TERMINAL_OFF_PREMISES is used. * `sourceOfFunds.type = CARD` 5. In addition to the standard fields, the following response fields are returned for a successful authorization. * `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` ### AUTHORIZE request example for decryption in your server {#authorize-request-example-for-decryption-in-your-server} ```json { "apiOperation": "AUTHORIZE", "order": { "amount": "30.10", "currency": "USD", "walletProvider": "APPLE_PAY" }, "sourceOfFunds": { "provided": { "card": { "number": "512345000000X008", Replace "X" with "0" "expiry": { "month": "01", "year": "39" }, "devicePayment": { "cryptogramFormat": "3DSECURE", "onlinePaymentCryptogram": "IA/8pdiWftSsxpFT6wABoDABhgA=", "eciIndicator": "20" } } }, "type": "CARD" }, "device": { "ani": "12341234" }, "transaction": { "source": "INTERNET" } } ``` The response is similar regardless of whether the decryption happens in the gateway or your server. ## Testing your Apple Pay integration {#testing-your-apple-pay-integration} To test your Apple Pay integration using your test merchant profile and a supported FPAN as provided by Apple for [Sandbox testing](https://developer.apple.com/apple-pay/sandbox-testing/). 1. Configure your app to use the 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. 2. If the gateway decrypts the payment token, procure a signed certificate from Apple and upload it to the gateway through Merchant Administration in production using your gateway test merchant profile. The gateway uses the certificate to decrypt the payment token. 3. If you decrypt the payment token in your server, use the DPAN from the decrypted token to perform test transactions. If the `response.gatewayCode` field indicates that the transactions are APPROVED or DECLINED, the gateway could process your test transactions successfully. ### Testing Apple Pay integration with gateway test data {#testing-apple-pay-integration-with-gateway-test-data} You can test your integration with the gateway in production using your test merchant profile with a valid [test card](https://developer.apple.com/apple-pay/sandbox-testing/) and provide the order amount value as provided in the following table to get the expected simulated response. | Order amount | Response | |--------------|---------------------| | 5656 | Approved | | 5757 | Declined | | 5858 | TIMED_OUT | | 5959 | UNSPECIFIED_FAILURE | | 6161 | Partially Approved | | 6262 | System Error | | 6363 | UNKNOWN | Configure your app to use the 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 the gateway decrypts the payment token, you must procure a signed certificate from Apple and upload it to the gateway through 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, DECLINED, or any other responses as per the order amount simulation, or based on the supported FPAN as provided by Apple, then the gateway can process your test transactions successfully. ## Apple Pay with the Mobile SDK {#apple-pay-with-the-mobile-sdk} The Mobile SDK helps you develop a mobile app that accepts Apple Pay payments through the gateway. The gateway offers support for Apple Pay through the Mobile SDK. Click [here](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/mc-gw-ios-sdk/index.md) for the Mobile SDK integration guidelines for the iOS platform.