Overview
This guide describes the steps to integrate Apple Pay as a Nuvei APM (alternative payment method) into your payment and payout flows using the Nuvei Server-to-Server REST API platform.
Prerequisites and Notes
You can send payment requests in these situations:
- As the next step of the Dynamic Apple Pay Button implementation.
- When you manage the Apple Pay Button yourself in your own payment flow, and now you want to send a payment request.
Apple Pay Integrations
Nuvei supports these integrations:
- Payment with Apple Pay Token
This allows you to send the encrypted Apple Pay token in a/payment
request. - Payment with Decrypted Apple Pay Token
You can decrypt the Apple Pay token, and then send the extracted payment details in anexternalMPI
block in a/payment
request. - Recurring Payments
You can perform both Initial Recurring Payments and Subsequent Recurring Payments using the encrypted Apple Pay token. - Payouts (withdrawals)
Apple Pay as an “External token provider”
An external token provider is a type of entity in the payment industry with its own flow (for example: Apple Pay, Google Pay, Visa Checkout).
These providers typically collect the customer payment method and transaction details.
Test Your Integration
After completing the relevant integration steps, test your Apple Pay integration in the Apple Pay Sandbox environment using the test credit and debit cards provided.
See the Apple Pay Integration Testing topic.
Payments
You can use the card details stored the in the Apple Pay token to send a /payment
request in the following ways:
- Use the encrypted Apple Pay token to send a Payment with Apple Pay Token.
- Or, you can decrypt the Apple Pay token and send the extracted card details in a Payment with Decrypted Apple Pay Token.
Payment with Apple Pay Token
Perform these steps to process an Apple Pay payment:
- Generate a
sessionToken
(the authentication token) required for the API calls by sending a/getSessionToken
. - Send the Apple Pay token in a
/payment
request.
Call the/payment
REST API request with its mandatory parameters. Include the data received on your server, in theexternalToken
block with these parameters:"userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
"externalTokenProvider"="ApplePay"
"mobileToken"=
[the encrypted data generated by Apple Pay from the device by a function defined insc_api_applepay.min.js
]
Example
/payment
Request using Apple Pay Token{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "amount": "200", "currency": "USD", "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>", "paymentOption": { "card": { "externalToken": { "externalTokenProvider": "ApplePay", "mobileToken": "<token received from Apple Pay>" } } }, "billingAddress": { "email": "john.smith@email.com", "country": "US" }, "deviceDetails": { "ipAddress": "127.0.0.1" }, "userDetails": { "country": "US" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example
/payment
Response using Apple Pay Token{ "reason": "", "authCode": "0E5E04", "orderId": "36726421", "transactionStatus": "APPROVED", "clientRequestId": "V8UE4312Y", "customData": "Custom Data for C-Panel Reports", "internalRequestId": 19054731, "version": "1.0", "transactionId": "2110000000005034514", "merchantSiteId": "126006", "transactionType": "Sale", "gwExtendedErrorCode": 0, "gwErrorCode": 0, "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "userPaymentOptionId": "8107431", "card": { "issuerBankName": "Legence Bank", "ccCardNumber": "4****1112", "externalTokenProvider": "ApplePay", "bin": "417577", "avsCode": "", "threeD": {}, "ccExpMonth": "08", "ccExpYear": "25", "isPrepaid": "false", "acquirerId": "18", "cardBrand": "VISA", "cvv2Reply": "", "last4Digits": "1112" } }, "sessionToken": "f3b77f95-d126-40bc-b1a9-2cf24fff811d", "userTokenId": "9XL74BK99KBW", "externalTransactionId": "", "fraudDetails": { "score": "0", "system": { "systemId": "1", "decision": "None" }, "finalDecision": "Accept" }, "status": "SUCCESS" }
When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.
Payment with Decrypted Apple Pay Token
You can decrypt the Apple Pay token yourself and then send the extracted card details in an externalMPI
block in a /payment
request.
/payment
REST API request with its mandatory parameters and include the following (as shown below):
-
- paymentOption.card.
"brand"
- paymentOption.card.
"last4Digits"
- deviceDetails.
"deviceManufacturerIdentifier"
- The
externalMpi
block containing relevant card details extracted from the decrypted token.
- Any other relevant data received on your server.
"userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
- paymentOption.card.
Example /payment
Request with Decrypted Apple Pay Token
{ "sessionToken":"<sessionToken from getSessionToken>", "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "amount":"200", "currency":"USD", "userTokenId":"<unique customer identifier in merchant system - required for UPO creation>", "clientUniqueId":"<unique transaction ID in merchant system>", "paymentOption":{ "card":{ "cardNumber":"4180620070230189", "cardHolderName":"John Smith", "expirationMonth":"05", "expirationYear":"2023", "CVV":"217", "brand":"VISA", "last4Digits":"5761", "threeD":{ "externalMpi":{ "eci":"5", "externalTokenProvider":"ApplePay", "cavv":"YwAAAfQAL9ivMOMCCuTzgLlgAgA=" } } } }, "billingAddress":{ "email":"john.smith@email.com", "country":"US" }, "deviceDetails":{ "ipAddress":"127.0.0.1", "deviceManufacturerIdentifier":"iPhoneX" }, "userDetails": { "country": "US" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.
Recurring Payments
You can perform both Initial Recurring Payments and Subsequent Recurring Payments using the encrypted Apple Pay token.
Follow these steps to integrate Apple Pay recurring payments into your payment flow.
Recurring payments involves two types of payments:
Initial Recurring Payment
The first request is initiated by the customer.Send an initial recurring
/payment
request with its mandatory parameters, and include these additional parameters:
"userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
"isRebilling":"0"
– To indicate that this is the initial transaction.- Include the authorized payment token (
mobileToken
) received from Apple Pay, in theexternalToken
block, with these parameters:"externalTokenProvider"="ApplePay"
"mobileToken"=
[the encrypted data generated by Apple Pay from the device by a function defined insc_api_applepay.min.js
]
Example Initial Recurring /payment
Request
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "amount": "200", "currency": "USD", "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId":"<unique transaction ID in merchant system>", "isRebilling":"0", "paymentOption":{ "card":{ "externalToken":{ "externalTokenProvider":"ApplePay", "mobileToken":"<token received from Apple Pay>" } } }, "billingAddress":{ "email": "john.smith@email.com", "country": "US" }, "userDetails":{ "email": "john.smith@email.com", "country": "US" }, "deviceDetails":{ "ipAddress": "127.0.0.1" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example Initial Recurring /payment
Response
{ "reason":"", "orderId":"36733461", "customData":"Custom Data Inserted By Darin!", "merchantSiteId":"126006", "gwExtendedErrorCode":0, "merchantId":"2502136204546424962", "paymentOption":{ "userPaymentOptionId":"8108371", "card":{ "issuerBankName":"", "ccCardNumber":"4****6635", "externalTokenProvider":"ApplePay", "bin":"481852", "avsCode":"", "threeD":{}, "cardType":"Credit", "ccExpMonth":"12", "ccExpYear":"23", "issuerCountry":"CA", "isPrepaid":"false", "acquirerId":"18", "cardBrand":"VISA", "cvv2Reply":"", "last4Digits":"6635" } }, "externalTransactionId":"", "authCode":"", "transactionStatus":"DECLINED", "clientRequestId":"KZEEYKRQX", "internalRequestId":19061331, "gwErrorReason":"Timeout\/Retry", "version":"1.0", "transactionId":"2110000000005045505", "transactionType":"Sale", "gwErrorCode":-1, "clientUniqueId":"695701003", "errCode":0, "sessionToken":"50cf4fb2-5ed8-48f3-a84d-08eec9b74835", "userTokenId":"PBT5K6CLFR4R", "fraudDetails":{ "score":"0", "system":{ "systemId":"1", "decision":"None" }, "finalDecision":"Accept" }, "status":"SUCCESS" }
When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.
Subsequent Payments
Subsequent recurring payments are initiated by you (with the customer’s consent).
Send /payment
requests with their mandatory parameters, and include the following additional parameters:
"isRebilling":"1"
– To indicate that it is a subsequent transaction."relatedTransactionId"
– ThetransactionId
of the initial payment."userPaymentOptionId"
– The UPO returned from the initial request.
Example Subsequent Recurring /payment
Request
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId":"<unique transaction ID in merchant system>", "amount": "200", "currency": "USD", "userTokenId": "<unique customer identifier in merchant system>", "isRebilling":"1", "relatedTransactionId": "<transactionId of the initial payment>", "paymentOption":{ "userPaymentOptionId":"8102901" }, "billingAddress":{ "email": "john.smith@email.com", "country": "US" }, "userDetails":{ "email": "john.smith@email.com", "country": "US" }, "deviceDetails":{ "ipAddress": "127.0.0.1" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example Subsequent Recurring /payment
Response
{ "reason":"", "orderId":"36733471", "customData":"Custom Data Inserted By Darin!", "merchantSiteId":"126006", "gwExtendedErrorCode":0, "merchantId":"2502136204546424962", "paymentOption":{ "userPaymentOptionId":"8102901", "card":{ "issuerBankName":"", "ccCardNumber":"4****6635", "bin":"481852", "avsCode":"R", "threeD":{}, "cardType":"Credit", "ccExpMonth":"12", "ccExpYear":"23", "issuerCountry":"CA", "isPrepaid":"false", "acquirerId":"103", "cardBrand":"VISA", "cvv2Reply":"", "last4Digits":"6635" } }, "externalTransactionId":"", "authCode":"", "transactionStatus":"DECLINED", "clientRequestId":"A55EDM1F6", "internalRequestId":19061351, "merchantDetails":{ "customField1":"customField1-valueU", "customField2":"customField2-valueU" }, "gwErrorReason":"Invalid Issue Number", "version":"1.0", "transactionId":"2110000000005045506", "transactionType":"Sale", "gwErrorCode":-1, "clientUniqueId":"695701003", "errCode":0, "sessionToken":"b24ec120-1379-436c-b027-990dc388a799", "userTokenId":"N882JFJUUNW7", "fraudDetails":{ "score":"0", "system":{ "systemId":"1", "decision":"None" }, "finalDecision":"Accept" }, "status":"SUCCESS" }
When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.
Payout (withdrawal)
The /payout
request can only be performed using a UPO (representing the customer payment method).
Call the /payout
request and include the userTokenId
, urlDetails.notificationUrl
, and the relevant userPaymentOptionId
.
Example /payout
Request
{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "userTokenId":"G480LNG2WYJ7", "clientUniqueId":"<unique customer identifier in merchant system>", "clientRequestId":"<unique request ID in merchant system>", "currency":"USD", "amount":"35", "userPaymentOption":{ "userPaymentOptionId":"8042761" }, "deviceDetails":{ "deviceType":"DESKTOP", "deviceName":"iPhone 5s", "deviceOS":"iOS 10.2", "browser":"safari", "ipAddress":"192.168.2.38" }, "urlDetails":{ "notificationUrl":"<The URL to which DMNs are sent>" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
Example /payout
Response
{ "reason":"", "transactionStatus":"APPROVED", "clientRequestId":"P5S49XKXW", "internalRequestId":17661371, "version":"1.0", "transactionId":"2110000000004199304", "merchantSiteId":"126006", "merchantId":"2502136204546424962", "clientUniqueId":"695701003", "errCode":0, "userPaymentOptionId":"8042761", "paymentMethodErrorCode":"0", "userTokenId":"G480LNG2WYJ7", "externalTransactionId":"2110000000065431", "status":"SUCCESS" }
Example /payout
DMN Response
A DMN is sent to the urlDetails.notificationUrl
provided in the request:
ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36234281&userid=G480LNG2WYJ7&merchant_unique_id=695701003&customData=Custom+Data+Inserted&productId=&first_name=&last_name=&email=¤cy=USD&clientUniqueId=695701003&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&acquirerId=null&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_VIP_Preferred&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-07-28.11%3A39%3A29&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=G480LNG2WYJ7&userPaymentOptionId=8042761&TransactionID=2110000000004199304&externalTransactionId=2110000000065431&totalAmount=35.0&dynamicDescriptor=Cashier+API&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20210712&type=DEPOSIT&clientRequestId=P5S49XKXW&relatedTransactionId=&responsechecksum=5446cc906f162a5e9eb34848942eb0b7&advanceResponseChecksum=b3f376ba2b970751af497b922d8daa34
When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.