Apple Pay (REST API)

Home    APMs    Apple Pay    Apple Pay Integration    Apple Pay (REST API)

On this page:

Overview

This guide describes the steps to integrate Apple Pay into your payment and payout flows using the Nuvei Server-to-Server REST API platform.

The integration steps described below are for Beta Testing purposes.
Please contact a Nuvei Integration Specialist for assistance.

Nuvei supports both 3D-Secure and Non-3D-Secure integrations.

To use the 3D-Secure integration, contact the Nuvei Integration Team to enable Apple Pay 3D processing in your merchant account.

Integrations Supported by Nuvei

  • Payments
    • Nuvei Decrypts the Token (non-3DS Payments)
      You can send the Apple Pay token “as-is” in a non-3DS /payment request, and “behind the scenes”, Nuvei decrypts and uses the relevant data extracted from the token.

      For special cases, please contact the Nuvei Integration Team to enable Apple Pay 3D payments.

    • Merchant Decrypts the Token (non-3DS Payments)
      You can decrypt the Apple Pay token, and then use the relevant data extracted from the token to send a /payment request without performing any additional 3DS authentication on the card.
    • Recurring Payments
      You can perform both Initial Recurring Payments and Subsequent Recurring Payments using the encrypted Apple Pay token.
  • Payouts (withdrawals)
    Use the /payout request to perform a withdrawal.

Apple Pay also supports refunds.


Prerequisites and Notes

  • The first time a card is used in the Apple Pay system, Apple Pay performs a 3DS authentication and stores the 3DS values from the successful Apple Pay authentication in an Apple Pay token.

    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.

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 and Google Pay).
These providers typically:

  • Collect the customer payment method and transaction details.
  • In some cases, they perform 3D-Secure authentication and provide the 3D-Secure authentication values.

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.

Nuvei Decrypts Token (non-3DS Payments)

This allows you to send the Apple Pay token in a /payment request without sending any 3DS values.

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.

The Apple Pay token contains Apple Pay authentication values from a successful Apple Pay authentication. You can send the Apple Pay token “as-is” in a /payment request, and “behind the scenes”, Nuvei decrypts and uses the relevant data contained in the token.

Call the /payment REST API request with its mandatory parameters. Include the data received on your server, in the externalToken class with these parameters:

  • paymentOption.card.externalToken.externalTokenProvider=”ApplePay“
  • paymentOption.card.externalToken.mobileToken: “<encrypted data generated by Apple Pay from the device by a function defined in sc_api_applepay.min.js>“
  • userTokenId:”<unique customer identifier in merchant system – required for UPO creation>“
Example /payment Request for Non-3DS
{
  "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 by ApplePay>"
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payment Response for Non-3DS

The ccCardNumber and last4Digits response values represent the customer’s real card number.

{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for Control 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.

Merchant Decrypts Token (non-3DS Payments)

The integration steps described below are for Beta Testing purposes.
Please contact a Nuvei Integration Specialist for assistance.

We have included a description of how the old “Merchant Decrypts Token” integration works; press here for details.

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 decrypt the Apple Pay token and send a payment request.

The Apple Pay token contains Apple Pay authentication values from a successful Apple Pay authentication. You can decrypt the Apple Pay token, and then use the relevant data extracted from the token to send a /payment request without performing any additional 3DS authentication on the card.

Decrypt the Apple Pay token yourself, and send relevant extracted data by calling a /payment REST API request with its mandatory parameters, and include the following (as shown below):

  • userTokenId
  • paymentOption.card.cardNumber
  • paymentOption.card.expirationMonth
  • paymentOption.card.expirationYear
  • paymentOption.card.brand(press here to see possible values)
  • paymentOption.card.last4Digits
  • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
  • paymentOption.card.externalToken.cryptogram: “<cryptogram from Apple Pay>“
  • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>” (Optional)
  • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
  • Any other relevant data received on your server.
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":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU=",
        "eciProvider":"5",
      }
    }
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  "userDetails": {
    "country":"US"
  }, 
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
Example /payment Response for Non-3DS
{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for Control 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****0496",
            "externalTokenProvider": "ApplePay",
            "bin": "4390189",
            "avsCode": "",
            "threeD": {
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "isPrepaid": "false",
            "acquirerId": "18",
            "cardBrand": "VISA",
            "cvv2Reply": "",
            "last4Digits": "0496"
        }
    },
    "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.

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 involve 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:
  • isRebilling:”0” – To indicate that this is the initial transaction.
  • Include the authorized payment token (mobileToken) received from Apple Pay, in the externalToken class, with these parameters:
    • externalTokenProvider: “ApplePay“
    • mobileToken: “<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 openOrder or 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": "[email protected]",
    "country": "US"
  },
  "userDetails":{
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example Initial Recurring /payment Response

The ccCardNumber and last4Digits response values represent the customer’s real card number.

{
  "reason":"",
  "orderId":"36733461",
  "customData":"Custom Data",
  "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:

  • userTokenId
  • isRebilling: “1” – To indicate that it is a subsequent transaction
  • relatedTransactionId: “<transactionId of the initial payment>“
  • userPaymentOptionId: <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": "[email protected]",
    "country": "US"
  },
  "userDetails":{
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example Subsequent Recurring /payment Response
{
  "reason":"",
  "orderId":"36733471",
  "customData":"Custom Data",
  "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"
}

Payout (Withdrawal) Flow

Gaming and Gambling merchants who wish to process a card payout transaction must provide cardData.cardHolderName to the payout request. Without this parameter, a payout may be rejected by the card schemes.

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.

Press here for more information about updating and/or adding user details.

Example /payout Request
{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "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":"<customer's IP address>",
        "deviceManufacturerIdentifier":"iPhoneX"
    },
    "urlDetails":{
        "notificationUrl":"<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

A Direct Merchant Notification (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.

Appendices

brand Values

Visa
Mastercard
Maestro
AMEX
Diners
Discover

Merchant Decrypts Token (Old)

This is a description of how the old “Merchant Decrypts Token” integration works.

The old “Merchant Decrypts Token” only works as a non-3DS flow.

If you want to use a 3DS flow integration where you can decrypt the Apple Pay token and then send the relevant data extracted in a /payment request, then:

  • Contact the Nuvei Integration Team to enable ApplePay 3D processing in your merchant account.
  • See the details of our new flow in the Merchant Decrypts Token section above.

The following description assumes that your merchant account is still not enabled for Apple Pay 3D processing.

After you decrypt the Apple Pay token yourself, send the extracted card details in an externalMPI class 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(press here to see possible values)
  • paymentOption.card.last4Digits
  • userTokenId
  • paymentOption.card.threeD.externalMpi (class containing relevant card details extracted from the decrypted token)
  • paymentOption.card.threeD.externalMpi.eci: “<eci value>” (Optional)
  • paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“
  • paymentOption.card.threeD.externalMpi.externalTokenProvider: “ApplePay“
  • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
Example /payment Request – Only 3DS Parameters Extracted from the Decrypted Apple Pay Token
{ 
  ...
  "paymentOption":{
    "card":{ 
      ...
      "brand":"VISA",
      "last4Digits":"0189",
      "threeD":{
        "externalMpi":{
          "eci":"5",
          "externalTokenProvider":"ApplePay",
          "cavv":"YwAAAfQAL9ivMOMCCuTzgLlgAgA="
        }
      }
    }
  },
  "deviceDetails":{
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  ...
}
Full 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",
      "expirationMonth":"05",
      "expirationYear":"2023",
      "CVV":"217",
      "brand":"VISA",
      "last4Digits":"0189",
      "threeD":{
        "externalMpi":{
          "eci":"2",
          "externalTokenProvider":"ApplePay",
          "cavv":"YwAAAfQAL9ivMOMCCuTzgLlgAgA="
        }
      }
    }
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  "userDetails": {
    "country": "US"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Nuvei Decrypts Token (3DS Payments)

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.

The Apple Pay token contains Apple Pay authentication values from a successful Apple Pay authentication. You can send the Apple Pay token “as-is” in a /payment request, and “behind the scenes”, Nuvei decrypts and uses the relevant data contained in the token.

Perform these steps:

1. Initialize the Payment

The /initPayment request determines if the card supports 3D-Secure and initializes the payment in the Nuvei system.

Send an /initPayment request with its mandatory parameters and include these additional parameters:

  • userTokenId
  • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
  • paymentOption.card.externalToken.mobileToken: “<encrypted data generated by Apple Pay from the device by a function defined in sc_api_applepay.min.js>“
  • paymentOption.card.threeD.methodNotificationUrl
    Including this is required for 3D-Secure v2 Web Browser Fingerprinting. (The issuer uses this URL to return fingerprinting notifications.)
Example /initPayment 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 – required for UPO creation>",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "ApplePay",
        "mobileToken": "<token received from Apple Pay>"
      },
      "threeD": {        
        "methodNotificationUrl": "<methodNotificationURL>"
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  }
}

2. Handling /initPayment

The /initPayment response determines the next step:

  • paymentOption.card.threeD.v2supported: “false“:
    This means the card does not support 3DS at all.
    Process the payment in the non-3DS flow.
  • paymentOption.card.threeD.v2supported: “true“:
    Continue with the 3DS-v2 payment flow below.
Example /initPayment Response – v2supported: “true”
{
  "reason": "",
  "orderId": "33704071",
  "transactionStatus": "APPROVED",
  "customData": "merchant custom data",
  "internalRequestId": 10036001,
  "version": "1.0",
  "transactionId": "2110000000000587378",
  "merchantSiteId": "142033",
  "transactionType": "InitAuth3D",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "merchantId": "427583496191624621",
  "clientUniqueId": "12345",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "issuerCountry": "US",
      "ccCardNumber": "5****5761",
      "bin": "511142",
      "cardType": "Credit", 
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "last4Digits": "5761",
      "threeD": {
        "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
        "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
        "v2supported": "true",
        "version": "2.2.0",
        "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
        "directoryServerId": "A000000003",
        "directoryServerPublicKey": "MIIFrjCCBJagAwIBAgIQB2rJm.."
      }
    }
  },
  "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
  "userTokenId": "230811147",
  "status": "SUCCESS"
}

3. Processing a Payment

This allows you to perform 3D authentication on the card using Nuvei (in addition to the Apple Pay authentication).

The remaining steps to process a 3D-Secure v2 payment for an Apple Pay payment are almost identical to the standard server-to-server REST payment flow.
Perform the following standard REST payment flow steps by pressing the link to see the steps, and perform the steps together with any changes indicated below:

a. 3D-Secure Fingerprinting

Perform steps as-is (no changes).

b. 3D-Secure v2 Payment Request

Perform the standard steps and include the relevant data from the 3D-Secure Fingerprinting, and the following parameters (as shown below):

  • userTokenId
  • relatedTransactionId
  • Instead of “actual card details” or a paymentOption.userPaymentOptionId, substitute the following:
    • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
    • paymentOption.card.externalToken.mobileToken: “<encrypted data generated by Apple Pay from the device by a function defined in sc_api_applepay.min.js>“
  • paymentOption.card.threeD class containing relevant data returned from the 3D-Secure Fingerprinting.
  • billingAddress and paymentOption classes that contain mandatory parameters.
Example /payment Request with 3D-Secure v2 Parameters
{
  "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>",
  "relatedTransactionId": "<initPayment TransactionId>",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "ApplePay",
        "mobileToken": "<token received from Apple Pay>"
      },
      "threeD": {
        "methodCompletionInd": "Y",
        "version": "2.2.0",
        "notificationURL": "<notificationURL>",
        "merchantURL": "<merchantURL>",
        "platformType": "02",
        "v2AdditionalParams": {
          "challengePreference": "02",
          "challengeWindowSize": "05"
        },
        "browserDetails": {
          "acceptHeader": "text/html,application/xhtml+xml",
          "ip": "192.168.1.11",
          "javaEnabled": "TRUE",
          "javaScriptEnabled": "TRUE",
          "language": "EN",
          "colorDepth": "48",
          "screenHeight": "400",
          "screenWidth": "600",
          "timeZone": "0",
          "userAgent": "Mozilla"
        }
      }
    }
  },
  "billingAddress": {
    "country": "US",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

c. 3D-Secure Challenge

Conditional – Only when a challenge is required.

d. Final Payment Request

Conditional – Based on the outcome of the 3D-Secure Challenge, you may need to send a final Liability Shift /payment request:

Sending a Final Liability Shift /payment Request

Complete the payment by sending a /payment request with its mandatory parameters and include these additional parameters:

  • userTokenId
  • relatedTransactionId
  • Instead of “actual card details” or a paymentOption.userPaymentOptionId, substitute the following:
    • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
    • paymentOption.card.externalToken.mobileToken: “<encrypted data generated by Apple Pay from the device by a function defined in sc_api_applepay.min.js>“
Example Liability Shift /payment Request (3D-Secure v2)
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantSiteId>",
  "merchantSiteId":"<your merchantId>",
  "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>",
  "relatedTransactionId":"<transactionId of the first payment request>",
  "paymentOption":{
    "card":{
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "mobileToken":"<token received from Apple Pay>"
      },
      "threeD":{
        "methodCompletionInd":"Y",
        "version":"2.2.0",
        "notificationURL":"<notificationURL>",
        "merchantURL":"<merchantURL>",
        "platformType":"02",
        "v2AdditionalParams":{
          "challengePreference":"02",
          "challengeWindowSize":"05"
        },
        "browserDetails":{
          "acceptHeader":"text/html,application/xhtml+xml",
          "ip":"192.168.1.11",
          "javaEnabled":"TRUE",
          "javaScriptEnabled":"TRUE",
          "language":"EN",
          "colorDepth":"48",
          "screenHeight":"400",
          "screenWidth":"600",
          "timeZone":"0",
          "userAgent":"Mozilla"
        }
      }
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
Liability Shift /payment (3D-Secure v2) Response

The response includes these parameters:

  • Returned from the external token provider:
    • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>“
  • Returned from the 3DS authentication process:
    • paymentOption.card.threeD.externalMpi.eci: “<eci value>“
    • paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“

The ccCardNumber and last4Digits response values represent the customer’s real card number.

Example Liability Shift /payment (3D-Secure v2) DMN

A DMN is sent to you containing the response details of the request:

...'ppp_status=FAIL&Status=ERROR&ExErrCode=1289&ErrCode=-1100&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Issuer+data+is+not+available%2C+please+try+again+later&ReasonCode=1289&PPP_TransactionID=37893001&userid=ZDMIYVPRAJCB&merchant_unique_id=695701003&customData=Custom+Data%21&productId=MAH3ST7266GM&first_name=Wxjtyskuuj&last_name=Pauwbeuyid&email=jhahn.jhnui%40srzaw.cb&currency=EUR&clientUniqueId=695701003&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=Germany&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=5****0902&bin=535275&noCVV=&acquirerId=99&expMonth=12&expYear=25&Token=SABHAGUAUABuAFAAMAAwAGQAZAAwAEYAbgAyAEgAZwBoADYARgAlACgAUABFAF0ANgB0AHgAVgBSAHkANABbAHoAJQBTAFMAeQAsAEMAeABjAHQAcgBfADgAPgBnAE0AXABiAGwAMwA%3D&tokenId=1688429575&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=Mlxdwieffa&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&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=ERROR&merchantLocale=&unknownParameters=&payment_method=cc_card&ID=&merchant_id=2502136204546424962&responseTimeStamp=2022-08-01.07%3A57%3A52&buyButtonProductId=&webMasterId=9IFAQ4ARB0IX&appliedPromotions=&uniqueCC=RHZ4oBPNguWJuqKZFoGGpmzIDw0%3D&transactionType=Auth&externalEmail=&cardCompany=MasterCard&eci=2&user_token_id=ZDMIYVPRAJCB&userPaymentOptionId=8303261&TransactionID=2110000000006785046&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&systemID=1&systemDecision=None&totalAmount=35.0&dynamicDescriptor=Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=0&externalToken_cardAcquirerId=0&externalToken_cardAcquirerName=&externalToken_cardBin=0&externalToken_cardBrandId=0&externalToken_cardBrandName=&externalToken_cardExpiration=0&externalToken_cardLength=0&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=0&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=0&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=5&upoRegistrationDate=20220801&cavv=kHQxQjBDQTAyRDlDNEE0NzRFMTc%3D&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=16WH99KFX&relatedTransactionId=2110000000006785044&externalTokenProvider=ApplePay&threeDSVersion=2.1.0&isLiabilityOnIssuer=1&challengePreferenceReason=0&lastFourDigits=0902&responsechecksum=36291b228a50daceaeccfb5b563df484&advanceResponseChecksum=c3c6afdf8fdeb352839e28d262d3aec5',

When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.

Merchant Decrypts Token (3DS Payments)

The integration steps described below are for Beta Testing purposes.
Please contact a Nuvei Integration Specialist for assistance.

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 decrypt the Apple Pay token and send a payment request.

The Apple Pay token contains Apple Pay authentication values from a successful Apple Pay authentication. You can decrypt the Apple Pay token, and then use the relevant data extracted from the token to send the following types of 3DS /payment requests:

  • External 3DS Provider
    If you use an external (third-party) 3DS provider to perform additional 3D card authentication, then you can include the 3DS authentication data provided by them, in the /payment request.
  • Nuvei as the 3DS Provider
    This allows you to send the relevant data extracted from the Apple Pay token a /payment request, as well as perform 3D authentication on the card using Nuvei (in addition to the Apple Pay authentication).

External 3DS Provider

If you use an external (third-party) 3DS provider to perform additional 3D card authentication, then you must include the 3DS authentication data provided by them, in the /payment request.

Decrypt the Apple Pay token yourself, and send relevant extracted data by calling a /payment REST API request with its mandatory parameters, and include the following (as shown below):

  • userTokenId
  • paymentOption.card.cardNumber
  • paymentOption.card.expirationMonth
  • paymentOption.card.expirationYear
  • paymentOption.card.brand (press here to see possible values)
  • paymentOption.card.last4Digits
  • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
  • paymentOption.card.externalToken.cryptogram: “<cryptogram from Apple Pay>“
  • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>” (Optional)
  • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
  • paymentOption.card.threeD.externalMpi (class containing relevant data 3DS authentication data provided by the external (third-party) 3DS provider.)
  • paymentOption.card.threeD.externalMpi.eci: “<eci value>“
  • paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“
  • paymentOption.card.threeD.externalMpi.dsTransID
  • Any other relevant data received on your server.
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":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD":{
        "externalMpi":{
          "eci":"2",
          "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
          "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600" 
        }
      }
    }
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  "userDetails": {
    "country":"US"
  }, 
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
Example /payment Response from Decrypted Apple Pay Token
{
  "reason": "",
  "authCode": "027203",
  "orderId": "36876651",
  "transactionStatus": "APPROVED",
  "clientRequestId": "PFYU0A4FK",
  "internalRequestId": 19297641,
  "version": "1.0",
  "transactionId": "2110000000005327976",
  "merchantSiteId": "126006",
  "transactionType": "Sale",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "externalSchemeTransactionId": "0302026300910298",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "userPaymentOptionId": "8128691",
    "card": {
      "issuerBankName": "Banco Mercantil do Brasil S.A.",
      "ccCardNumber": "4****0496",
      "bin": "439018",
      "avsCode": "G",
      "threeD": {},
      "cardType": "Credit",
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "issuerCountry": "BR",
      "isPrepaid": "false",
      "acquirerId": "103",
      "cardBrand": "VISA",
      "cvv2Reply": "",
      "last4Digits": "0496"
    }
  },
  "sessionToken": "50bfe77a-5b0b-498c-b9fc-c6523763715c",
  "userTokenId": "D3UERI4KDQK7",
  "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.

Nuvei as the 3DS Provider

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 decrypt the Apple Pay token, and send a payment request.

This allows you to decrypt the Apple Pay token and send the relevant data extracted from the Apple Pay token a /payment request, as well as perform 3D authentication on the card using Nuvei (in addition to the Apple Pay authentication), as described below:

1. Decrypt Apple Pay Token

Decrypt the Apple Pay token according to Apple Pay’s requirements.

2. Initialize the Payment

The /initPayment request determines if the card supports 3D-Secure and initializes the payment in the Nuvei system.

Send the relevant data extracted from the Apple Pay token in an /initPayment request with its mandatory parameters, and include the following (as shown below):

  • userTokenId
  • paymentOption.card.cardNumber
  • paymentOption.card.expirationMonth
  • paymentOption.card.expirationYear
  • paymentOption.card.brand (press here to see possible values)
  • paymentOption.card.last4Digits
  • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
  • paymentOption.card.externalToken.cryptogram: “<cryptogram from Apple Pay>“
  • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>” (Optional)
  • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
  • paymentOption.card.threeD.methodNotificationUrl
    Including this is required for 3D-Secure v2 Web Browser Fingerprinting. (The issuer uses this URL to return fingerprinting notifications.)
  • Any other relevant data received on your server.
Example /initPayment 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 – required for UPO creation>",
  "paymentOption": {
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD": {        
        "methodNotificationUrl": "<methodNotificationURL>"
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  }
}
Example /initPayment Response – v2supported: “true”
{
  "reason": "",
  "orderId": "33704071",
  "transactionStatus": "APPROVED",
  "customData": "merchant custom data",
  "internalRequestId": 10036001,
  "version": "1.0",
  "transactionId": "2110000000000587378",
  "merchantSiteId": "142033",
  "transactionType": "InitAuth3D",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "merchantId": "427583496191624621",
  "clientUniqueId": "12345",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "issuerCountry": "US",
      "ccCardNumber": "4****0496",
      "bin": "439018",
      "threeD": {
        "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
        "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
        "v2supported": "true",
        "version": "2.2.0",
        "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
        "directoryServerId": "A000000003",
        "directoryServerPublicKey": "MIIFrjCCBJagAwIBAgIQB2rJm.."
      },
      "cardType": "Credit", 
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "last4Digits": "0496"
    }
  },
  "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
  "userTokenId": "230811147",
  "status": "SUCCESS"
}
Example /initPayment Response – v2supported: “false”
{
  "reason": "",
  "clientRequestId": "E3YD6LSZD",
  "internalRequestId": 19125711,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "threeD": {
        "v2supported": "false"
      }
    }
  },
  "sessionToken": "3056e85e-6272-4c1c-999a-0519def10020",
  "userTokenId": "OHJD9R9CNLCF",
  "status": "SUCCESS"
}
3. Handling /initPayment

The /initPayment response determines the next step:

  • paymentOption.card.threeD.v2supported: “false“:
    This means the card does not support 3DS at all.
    Process the payment in the Non-3DS Payments flow (described above).
  • paymentOption.card.threeD.v2supported: “true“:
    Process the payment in the 4. Payments – 3DS-v2 flow.
4. 3DS v2 Payments

This allows you to perform 3D authentication on the card using Nuvei (in addition to the Apple Pay authentication).

The remaining steps to process a 3D-Secure v2 payment for an Apple Pay payment are almost identical to the standard server-to-server REST payment flow.
Perform the following standard REST payment flow steps by pressing the link to see the steps, and perform the steps together with any changes indicated below:

  1. 3D-Secure Fingerprinting
    Perform steps as-is (no changes).
  2. 3D-Secure v2 Payment Request
    Perform the standard steps and include the relevant data extracted from the Apple Pay token and from the 3D-Secure Fingerprinting (as shown below):
    • userTokenId
    • relatedTransactionId
    • paymentOption.card.cardNumber
    • paymentOption.card.expirationMonth
    • paymentOption.card.expirationYear
    • paymentOption.card.brand (press here to see possible values)
    • paymentOption.card.last4Digits
    • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
    • paymentOption.card.externalToken.cryptogram: “<cryptogram from Apple Pay>“
    • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>” (Optional)
    • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
    • paymentOption.card.threeD class containing relevant data returned from the 3D-Secure Fingerprinting.
    • Any other relevant data received on your server.
    Example /payment Request with 3D-Secure v2 Parameters
    {
  "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>",
  "relatedTransactionId": "<initPayment TransactionId>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD": {
        "methodCompletionInd": "Y",
        "version": "2.2.0",
        "notificationURL": "<notificationURL>",
        "merchantURL": "<merchantURL>",
        "platformType": "02",
        "v2AdditionalParams": {
          "challengePreference": "02",
          "challengeWindowSize": "05"
        },
        "browserDetails": {
          "acceptHeader": "text/html,application/xhtml+xml",
          "ip": "192.168.1.11",
          "javaEnabled": "TRUE",
          "javaScriptEnabled": "TRUE",
          "language": "EN",
          "colorDepth": "48",
          "screenHeight": "400",
          "screenWidth": "600",
          "timeZone": "0",
          "userAgent": "Mozilla"
        }
      }
    }
  },
  "billingAddress": {
    "country": "US",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
  3. 3D-Secure Challenge
    Conditional – Only when a challenge is required.
  4. Final Payment Request
    Conditional – Based on the outcome of the 3D-Secure Challenge, you may need to send a final Liability Shift /payment request:
    Sending a final Liability Shift /payment Request
    Complete the payment by sending a /payment request with its mandatory parameters and include these additional parameters:
    • userTokenId
    • relatedTransactionId
    • paymentOption.card.cardNumber
    • paymentOption.card.expirationMonth
    • paymentOption.card.expirationYear
    • paymentOption.card.brand (press here to see possible values)
    • paymentOption.card.last4Digits
    • paymentOption.card.externalToken.externalTokenProvider: “ApplePay“
    • paymentOption.card.externalToken.cryptogram: “<cryptogram from Apple Pay>“
    • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>” (Optional)
    • deviceDetails.deviceManufacturerIdentifier: “<value decrypted from Apple Pay token>“
    Example Liability Shift /payment Request (3D-Secure v2)
    {
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantSiteId>",
  "merchantSiteId":"<your merchantId>",
  "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>",
  "relatedTransactionId":"<transactionId of the first payment request>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"ApplePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      }
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>",
    "deviceManufacturerIdentifier":"iPhoneX"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
    Liability Shift /payment (3D-Secure v2) Response

    The response includes these parameters:

    • Returned from the external token provider:
      • paymentOption.card.externalToken.eciProvider: “<value from Apple Pay>“
    • Returned from the 3DS authentication process:
      • paymentOption.card.threeD.externalMpi.eci: “<eci value>“
      • paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“
    Example Liability Shift /payment (3D-Secure v2) DMN

    A DMN is sent to you containing the response details of the request:

    ...'ppp_status=FAIL&Status=ERROR&ExErrCode=1289&ErrCode=-1100&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Issuer+data+is+not+available%2C+please+try+again+later&ReasonCode=1289&PPP_TransactionID=37893001&userid=ZDMIYVPRAJCB&merchant_unique_id=695701003&customData=Custom+Data%21&productId=MAH3ST7266GM&first_name=Wxjtyskuuj&last_name=Pauwbeuyid&email=jhahn.jhnui%40srzaw.cb&currency=EUR&clientUniqueId=695701003&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=Germany&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=5****0902&bin=535275&noCVV=&acquirerId=99&expMonth=12&expYear=25&Token=SABHAGUAUABuAFAAMAAwAGQAZAAwAEYAbgAyAEgAZwBoADYARgAlACgAUABFAF0ANgB0AHgAVgBSAHkANABbAHoAJQBTAFMAeQAsAEMAeABjAHQAcgBfADgAPgBnAE0AXABiAGwAMwA%3D&tokenId=1688429575&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=Mlxdwieffa&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&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=ERROR&merchantLocale=&unknownParameters=&payment_method=cc_card&ID=&merchant_id=2502136204546424962&responseTimeStamp=2022-08-01.07%3A57%3A52&buyButtonProductId=&webMasterId=9IFAQ4ARB0IX&appliedPromotions=&uniqueCC=RHZ4oBPNguWJuqKZFoGGpmzIDw0%3D&transactionType=Auth&externalEmail=&cardCompany=MasterCard&eci=2&user_token_id=ZDMIYVPRAJCB&userPaymentOptionId=8303261&TransactionID=2110000000006785046&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&systemID=1&systemDecision=None&totalAmount=35.0&dynamicDescriptor=Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=0&externalToken_cardAcquirerId=0&externalToken_cardAcquirerName=&externalToken_cardBin=0&externalToken_cardBrandId=0&externalToken_cardBrandName=&externalToken_cardExpiration=0&externalToken_cardLength=0&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=0&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=0&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=5&upoRegistrationDate=20220801&cavv=kHQxQjBDQTAyRDlDNEE0NzRFMTc%3D&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=16WH99KFX&relatedTransactionId=2110000000006785044&externalTokenProvider=ApplePay&threeDSVersion=2.1.0&isLiabilityOnIssuer=1&challengePreferenceReason=0&lastFourDigits=0902&responsechecksum=36291b228a50daceaeccfb5b563df484&advanceResponseChecksum=c3c6afdf8fdeb352839e28d262d3aec5',

When implementing a Dynamic Apple Pay Button, then continue with the Backend to Frontend Transfer step.

Last update iconLast modified November 2024