Apple Pay Guide (REST API)

On this page:

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.

Coming Soon!

3D-Secure authentication support for Apple Pay is scheduled for release in mid-July.

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:

Apple Pay supports refunds.

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.

In response to a payment request, Apple Pay returns an encrypted Apple Pay token containing the transaction result, customer payment method, as well as other 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.

If you need help with any of the steps, please contact Nuvei’s Integration Team.

Payments

You can use the card details stored the in the Apple Pay token to send a /payment request in the following ways:

Including a userTokenId (unique customer identifier in the merchant system) in the /payment request:

  • Allows Nuvei to create a UPO (user payment option) record to store the customer payment method details.
  • The system returns an encrypted userPaymentOptionId which can be used in future transactions to represent the customer payment method.

If you do not wish to use Nuvei UPOs, then contact the Nuvei Integration Team to configure your merchant account accordingly.

Payment with Apple Pay Token

Perform these steps to process an Apple Pay payment:

  1. Generate a sessionToken (the authentication token) required for the API calls by sending a /getSessionToken. 
  2. 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 the externalToken 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 in sc_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.

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 by yourself in your own payment flow, and now you want to send a payment request.
Call the /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.

    Note, paymentOption.card.threeD.externalMpi."eci" is optional.

  • Any other relevant data received on your server.
  • "userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
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.

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 by yourself in your own payment flow, and now you want to send a payment request.

Follow these steps to integrate Apple Pay recurring payments into your payment flow.

Recurring payments involves two types of payments:

Initial Recurring Payment

You can send payment requests using the following steps in these situations:

  • As the next step of the Dynamic Apple Pay Button implementation.
  • When you manage the Apple Pay Button by yourself in your own payment flow, and now you want to send a payment request.

Including a userTokenId (unique customer identifier in the merchant system) in the /payment request:

  • Allows Nuvei to create a UPO (user payment option) record to store the customer payment method details.
  • The system returns an encrypted userPaymentOptionId which can be used in future transactions to represent the customer payment method.

If you do not wish to use Nuvei UPOs, then contact the Nuvei Integration Team to configure your merchant account accordingly.

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 the externalToken block, with these parameters:
    • "externalTokenProvider"="ApplePay"
    • "mobileToken"=[the encrypted data generated by Apple Pay from the device by a function defined in sc_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" – The transactionId 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=&currency=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.