On this page:

1. Authentication
2. Initialize 3DS
- Handling the /initPayment Response
3. Payment
4. 3DS Challenge
5. Final Payment Request
- Liability Shift – 3DS

This page describes the Server-to-Server REST 1.0 payment flow, which includes the following steps:

1. Authentication

Generate a sessionToken (the authentication token) required for the API calls, using one of these methods:

Sending a /getSessionToken API server-side request.
Initializing the SafeCharge Object

Sending a `/getSessionToken`

Send the /getSessionToken request with its mandatory parameters.

When calculating the checksum parameter value:

Concatenate the following fields in this order, with no spaces, and no separators between the fields:
merchantId, merchantSiteId,clientRequestId,timeStamp, merchantSecretKey
Calculate the SHA-256 hash of the concatenated fields.

Example `/getSessionToken` Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/getSessionToken` Response

The response returns a sessionToken, which is used in sending the /payment request.

{
  "sessionToken":"7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0",
  "internalRequestId":188635168,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"479748173730597238",
  "merchantSiteId":"180083",
  "version":"1.0",
  "clientRequestId":"20200510165419"
}

2. Initialize 3DS

If you are not using a 3D Secure (3DS) flow, then skip directly to the Non-3DS (without liability shift) section.

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

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

Provide the payment method (card) details by including either of these (not both):
- The paymentOption.card class with full card details (as shown below).
- Or, for a returning customer, you can provide their previously stored payment method, by including these parameters:
  - userTokenId
  - paymentOption.userPaymentOptionId: “<ID of a previously stored payment option>“
(Optional) If you intend to perform 3DS Fingerprinting (in the next step), then include:
- paymentOption.card.threeD.methodNotificationUrl
  (The methodNotificationURL is the URL to which the issuer should send the fingerprinting notification response.)

If the merchant is sending an /initPayment request after a soft decline for a previous /payment request, include relatedTransactionId and specify the transactionId from the response to that /payment request.

Example `/initPayment` Request

{
    "sessionToken": "<sessionToken from /getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in your system>",
    "clientRequestId": "<unique request ID in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "CL-BRW1",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": {
                "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    }
}

<?php
//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in your system>',
    'clientRequestId' => '<unique request ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'methodNotificationUrl'=>'<methodNotificationURL>',
            ]
        ]
    ],
    'deviceDetails'     => [
        "ipAddress"  => "<customer's IP address>"
    ],
]);
?>

{
    // Parameters needed for initPayment call
    String userTokenId = "<unique customer identifier in your system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "200";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("<customer's IP address>");

    InitPaymentThreeD threeD = new InitPaymentThreeD();
    threeD.setMethodNotificationUrl("<methodNotificationURL>");

    InitPaymentCard card = new InitPaymentCard();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("CL-BRW1");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setThreeD(threeD);

    InitPaymentOption initPaymentOption = new InitPaymentOption();
    initPaymentOption.setCard(card);

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.initPayment(userTokenId, clientUniqueId, clientRequestId, currency, amount, deviceDetails, initPaymentOption, null, null, null, null);
}

var response = safecharge.InitPayment(
    "USD",
    "200",
    new InitPaymentOption
    {
        Card = new InitPaymentCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new InitPaymentThreeD
            {
                MethodNotificationUrl = "<MethodNotificationUrl>",
            }
        }
    },
    userTokenId: "<unique customer identifier in your system>",
    orderId: "33704071",
    clientUniqueId: "<Transaction ID in your system>",
    clientRequestId: "<unique request ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

safecharge.paymentService.initPayment({
    userTokenId            : "<unique customer identifier in your system>",
    clientRequestId        : "<unique request ID in merchant system>",
    clientUniqueId         : "<unique transaction ID in merchant system>",
    amount                 : "200",
    currency               : "USD",
    paymentOption  : {
        card: {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                methodNotificationUrl : "<methodNotificationUrl>",
                }
        }
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});

Example `/initPayment` Response – `v2supported`: “true”

{
    "orderId": "276984098",
    "userTokenId": "<unique customer identifier in your system>",
    "transactionId": "1110000000011280648",
    "transactionType": "InitAuth3D",
    "transactionStatus": "APPROVED",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "cardType": "Credit",
            "issuerCountry": "GB",
            "threeD": {
                "methodUrl": "https://3dsn.sandbox.nuvei.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL",
                "version": "2.1.0",
                "v2supported": "true",
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjMzY2I0ODA0LTA0YmQtNDRhOC1hNmYzLTIxMjRmMDUwM2M3MSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "directoryServerId": "A000000003",
                "directoryServerPublicKey": "rsa;MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAst+HGfPPsX3p6HHEQ9YzourlQj16Nscmm13Cp7cZe4dZB2oWnJqZ7oh/pEoEoOAxBw1x4NFgXKTKdHAeu3VBNVw8SwMTdIC+X16VV+3VIyPbUvJXFp3QoR8WUwPB3F1Lb9SMFNS95boYDZKIOdPW0cP1dRi7pFugsBUZDCP/H3nFfBFHMCBoga+P3AHGj5y8RVpv0hS9jaIsYjX+i58B61OGCB7D0AiADNZJuFzw2+xpNkt6NJJF66FPO8qIh8xR2xGVDf7TtCbss/CugLRgSqKab9YRB8/TBTcy5bxj6O8HD6aL2zGLcMY9dCobXxCodLEtMjJdVL8N+iZrsI2gtwIDAQAB",
                "serverTransId": "33cb4804-04bd-44a8-a6f3-2124f0503c71"
            }
        }
    },
    "customData": "",
    "sessionToken": "3b2126a2-6778-4214-a8c4-269915d5b1e4",
    "internalRequestId": 234842078,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20210125143714"
}

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"
}

Handling the `/initPayment` Response

Choose a card authentication flow to process the payment based on either:

Your own business criteria, for example: “If the amount is less than 10, then use the Non-3DS (without liability shift)”, etc.
Or, you can base your choice on the values returned in the /initPayment response.
Perform the relevant flow:
- Non-3DS (without liability shift)
  If threeD.v2supported:”false“, then the card does not support 3DS.
  However, you can still send a non-3DS payment (without liability shift).
- 3DS
  If threeD.v2supported:”true“, then the card supports 3DS.

3. Payment

Process the payment according to the relevant card authentication flow:

Non-3DS (without liability shift)
3DS

Non-3DS Payment

To perform a non-3DS payment (without liability shift), send a /payment request with its mandatory parameters and include these additional parameters:

Only billingAddress.country and billingAddress.email are mandatory; however, providing the full billingAddress and shippingAddress classes improve the chances of achieving frictionless authentication
Calculate and include the checksum value as follows:
1. Concatenate the following parameters in this order, with no spaces, and no separators between the parameters:
  merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
2. Calculate the SHA-256 hash of the concatenated parameters.
If the merchant already sent an /initPayment request, then include relatedTransactionId and specify the transactionId returned in the /initPayment response.

Example `/payment` (Non-3DS) 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>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2030",
            "CVV":"217"
        }
    },
    "relatedTransactionId":"<transactionId returned from initPayment>", 
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "country":"US",
        "email":"[email protected]"
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.nuvei.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'John Smith',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217'
        ]
    ],
    'relatedTransactionId' => 'initPaymentTransactionId', // transactionId returned from initPayment
    'billingAddress' => [
        'firstName'   => "John",
        'lastName'   => "Smith",
        'country'   => 'US',
        'email'     => '[email protected]',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '<customer's IP address>',
    ],
]);
?>

//Initialize the SDK (see https://docs.nuvei.com/?p=29433)

{
    String userTokenId = "<unique customer identifier in your system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String currency = "USD";
    String amount = "200";

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");    

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("<customer's IP address>");

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, deviceDetails, billingAddress);
}

//Initialize the SDK (see https://docs.nuvei.com/?p=48413)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "initPaymentTransactionId", // transactionId returned from initPayment
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

//Initialize the SDK (see https://docs.nuvei.com/?p=53443)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    paymentOption  : {
        card : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "John Smith",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217"
        }
    },
    relatedTransactionId : "initPaymentTransactionId", // transactionId returned from initPayment
    billingAddress : {
        firstName : "John",
        lastName  : "Smith",
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Example `/payment` (Non-3DS) Response

{
    "orderId": "313694208",
    "paymentOption": {
        "userPaymentOptionId": "",
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "22",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "issuerBankName": "River Valley Credit Union",
            "issuerCountry": "GB",
            "isPrepaid": "false",
            "threeD": { }
        }
    },
    "transactionStatus": "APPROVED",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionType": "Sale",
    "transactionId": "711000000010529231",
    "externalTransactionId": "",
    "authCode": "111106",
    "customData": "",
    "sessionToken": "d59c50b1-a589-4085-8103-816e8e5fc173",
    "internalRequestId": 437119448,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20220502125226"
}

The process ends here.

3DS Payment

Follow the steps below to perform a 3DS payment.

Fingerprinting (Optional)

3DS Fingerprinting for Web Browsers is an optional authentication step for 3DS.

3DS Fingerprinting collects client side 3DS browser information using a hidden IFrame, and sends this data in a notification (containing the threeDSServerTransId and methodCompletionInd) to the credit card issuer (at the methodNotificationUrl).

Prerequisites: In the previous step (Initialize 3DS):

The methodNotificationURL must have been included in the /initPayment request.
The methodUrl and methodPayload parameters should have been returned in the /initPayment response.

Perform 3DS Fingerprinting:

Follow the steps in the 3DS Fingerprinting topic.

To perform a 3DS payment, send a /payment request with its mandatory parameters and include these additional parameters:

The threeD Input Class paymentOption.card.threeD containing v2AdditionalParams:
- If 3DS Fingerprinting was performed, then set the value of paymentOption.card.threeD.methodCompletionInd to the value returned.
- If 3DS Fingerprinting was not performed, then set the value of paymentOption.card.threeD.methodCompletionInd to “U” to indicate “unavailable”.
- IncludenotificationUrl, which should contain the URL to which the issuer should send a notification, after the 3DS challenge step. This URL is needed for the next step (3DS Challenge).
- version – The 3DS version supported by the card (from the response to the /initPayment request).
- challengePreference (optional) – The merchant’s challenge/exemption preference for each transaction, sent to the issuer during the 3DS decision stage.
  Possible values:
  - 01 – Challenge – You prefer that the issuer performs a challenge (even though this inconveniences your customer), and that the issuer ultimately accepts liability for the payment.
  - 02 – Exemption – You are willing to accept the risk (liability) for the payment. You do not want the issuer to perform a challenge.
  - 03 – No preference – This has the same effect as not sending the challengePreference parameter.
  - It is highly recommended not to use the optional challengePreference parameter for each transaction.
  - Instead, it is highly recommended to use the Nuvei Risk Engine (which is configured with your “challenge preferences” in your merchant account).
    The Risk Engine makes the “risk decision” based on proven industry best practices, customized to your own “challenge preferences”.
    Contact our Risk Team to enable the Risk Engine in your merchant account and configure your “challenge preferences”.
Set the relatedTransactionId value to the transactionId returned in the response to the /initPayment request.
billingAddress class containing:
- country
- email
- firstName
- lastName
- address
- phone (for 3DS card authentication if email not provided)
- zip
- city
- state
  
  Providing the full billingAddress and shippingAddress classes instead of only the mandatory parameters improves the chances of achieving frictionless authentication.
paymentOption class containing:
- card.cardNumber
- card.expirationMonth
- card.expirationYear
- card.cardHolderName
- card.threeD.browserDetails.ip (for 3DS card authentication)
- card.threeD.browserDetails.screenHeight (for 3DS card authentication)
- card.threeD.browserDetails.screenWidth (for 3DS card authentication)
Calculate and include the checksum value as follows:
1. Concatenate the following parameters in this order, with no spaces, and no separators between the parameters:
  merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
2. Calculate the SHA-256 hash of the concatenated parameters.

Example `/payment` Request for 3DS

{
    "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>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"CL-BRW1",
            "expirationMonth":"12",
            "expirationYear":"2030",
            "CVV":"217",
            "threeD":{
                "methodCompletionInd":"Y",
                "version":"2.1.0",
                "notificationURL":"<notificationURL>",
                "merchantURL":"<merchantURL>",
                "platformType":"02",
                "v2AdditionalParams":{
                    "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"
                }
            }
        }
    },
    "relatedTransactionId":"<transactionId returned from initPayment>",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "country":"US",
        "email":"[email protected]"
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.nuvei.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'version'=>'2.1.0',
                'notificationUrl'      => '<notificationURL>',
                'merchantUrl'          => '<merchantURL>',
                'platformType'         => '02',
                'v2AdditionalParams' =>[
                    'challengeWindowSize' =>'05',
                ],
                'browserDetails' =>[        // collected on the 3DS fingerprinting
                    'acceptHeader'      => 'text/html,application/xhtml+xml',
                    'ip'                => '190.0.23.160',
                    'javaEnabled'       => 'TRUE',
                    'javaScriptEnabled' => 'TRUE',
                    'language'          => 'EN',
                    'colorDepth'        => '48',
                    'screenHeight'      => '400',
                    'screenWidth'       => '600',
                    'timeZone'          => '0',
                    'userAgent'         => 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)'
                ]
            ]
        ]
    ],
    'relatedTransactionId' => 'initPaymentTransactionId', // transactionId returned from initPayment
    'billingAddress' => [
        'firstName'   => "John",
        'lastName'   => "Smith",
        'country'   => 'US',
        'email'     => '[email protected]',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '<customer's IP address>',
    ],
]);
?>

//Initialize the SDK (see https://docs.nuvei.com/?p=29433)

{
    String userTokenId = "<unique customer identifier in your system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String currency = "USD";
    String amount = "200";

    V2AdditionalParams v2AdditionalParams = new V2AdditionalParams();
    v2AdditionalParams.setChallengeWindowSize("05");

    BrowserDetails browserDetails = new BrowserDetails();
    browserDetails.setAcceptHeader("text/html,application/xhtml+xml");
    browserDetails.setIp("192.168.1.11");
    browserDetails.setJavaEnabled("TRUE");
    browserDetails.setJavaScriptEnabled("TRUE");
    browserDetails.setLanguage("EN");
    browserDetails.setColorDepth("48");
    browserDetails.setScreenHeight("400");
    browserDetails.setScreenWidth("600");
    browserDetails.setTimeZone("0");
    browserDetails.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)");

    ThreeD threeD = new ThreeD();
    threeD.setMethodCompletionInd("Y");
    threeD.setVersion("2.1.0");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setBrowserDetails(browserDetails);

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("CL-BRW1");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("<customer's IP address>");

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

//Initialize the SDK (see https://docs.nuvei.com/?p=48413)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new ThreeD
            {
                MethodCompletionInd = "Y",
                Version = "2.1.0",
                NotificationURL = "<notificationURL>",
                MerchantURL = "<merchantURL>",
                PlatformType = "02",
                V2AdditionalParams = new V2AdditionalParams
                {
                    ChallengeWindowSize = "05"
                },
                BrowserDetails = new 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/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "initPaymentTransactionId", // transactionId returned from initPayment
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

//Initialize the SDK (see https://docs.nuvei.com/?p=53443)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    paymentOption  : {
        card : {
            cardNumber      : "CL-BRW1",
            cardHolderName  : "john smith",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                methodCompletionInd  : "Y",
                version              : "2.1.0",
                notificationUrl      : "<notificationURL>",
                merchantUrl          : "<merchantURL>",
                platformType         : "02",
                v2AdditionalParams :{
                    challengeWindowSize : "05"
                browserDetails :{      // collected on the 3DS fingerprinting
                    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/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    relatedTransactionId : "initPaymentTransactionId", // transactionId returned from initPayment
    billingAddress : {
        firstName : "John",
        lastName  : "Smith",
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Example `/payment` Response for 3DS

In this case, the example below shows a response from the issuer with a transactionStatus: “REDIRECT“.

A “REDIRECT” response contains data used as the input values in the next step (3DS Challenge).

For example: paymentOption.card.threeD.cReq – (shown in the example below)
This is needed as input for 3DS challenges.

{
    "orderId": "277057469",
    "paymentOption": {
        "userPaymentOptionId": "",
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "22",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "threeD": {
                "threeDFlow": "1",
                "acsUrl": "https://3dsn.sandbox.nuvei.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL2RvY3Muc2FmZWNoYXJnZS5jb20vM0RzaW11bGF0b3Ivbm90aWZpY2F0aW9uVXJsLnBocCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOTIyNzgxZjEtMmZlYy00MGQ5LWIyYjUtYTMwMmZkMzRlNWI2IiwiYWNzVHJhbnNJRCI6ImQ1ZWMxMmRkLTQ1ZGUtNDRkYS04YjZmLWNhYjJjYzU0MTVkNCIsImRzVHJhbnNJRCI6IjdmN2UwZGNjLTg3ZTktNDkwYy1iOTFlLWNiZjgwOTdmYjllOSJ9",
                "eci": "5",
                "version": "2.1.0",
                "whiteListStatus": "",
                "cavv": "",
                "acsChallengeMandated": "Y",
                "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjkyMjc4MWYxLTJmZWMtNDBkOS1iMmI1LWEzMDJmZDM0ZTViNiIsImFjc1RyYW5zSUQiOiJkNWVjMTJkZC00NWRlLTQ0ZGEtOGI2Zi1jYWIyY2M1NDE1ZDQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
                "authenticationType": "01",
                "cardHolderInfoText": "",
                "sdk": {
                    "acsSignedContent": ""
                },
                "result": "C",
                "acsTransId": "d5ec12dd-45de-44da-8b6f-cab2cc5415d4",
                "dsTransID": "7f7e0dcc-87e9-490c-b91e-cbf8097fb9e9",
                "threeDReasonId": "",
                "isExemptionRequestInAuthentication": "0",
                "challengePreferenceReason": "12"
            }
        }
    },
    "transactionStatus": "REDIRECT",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000011302215",
    "externalTransactionId": "",
    "authCode": "",
    "customData": "",
    "sessionToken": "acb48e94-a464-48d8-846a-9142ed556231",
    "internalRequestId": 235059509,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20210126115246"
}

Handling the `/payment` Response

The /payment response includes:

The transactionStatus parameter that can have one of these values:
- REDIRECT – You must perform the 3DS Challenge step.
- APPROVED – Payment was approved and the (frictionless) payment was made.
  This can be due to one of these cases:
  - A cavv value is returned, the eci* value is either 5 (Visa) or 2 (Mastercard), and the issuer accepts liability (liability shift).
    *The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3DS program.
    The process ends here.
  - If you requested a 3DS Exemption, the issuer has approved a non-3DS transaction (the issuer does not accept liability (no liability shift).
    The process ends here.
- DECLINED – The payment was declined by the card issuer and the transaction should not proceed to payment.
  The process can end here.
  However, if the response is a soft decline – threeD.flow: “softDecline” – the merchant can send a new /initPayment request that includes the transactionId from this /payment response as the relatedTransactionId.
  
  The /paymentresponse also includes:
  - eci is a negative value and no cavv is returned.
  - errCode and errorDescription are returned.
- ERROR – An error occurred. The 3DS authentication failed.
  
  The process can end here.
  However, subject to risk considerations, the merchant can proceed with a Non-3DS (without liability shift) payment by simply submitting a /payment request without the threeD class.
  
  The /payment response also includes:
  - eci is a negative value and no cavv is returned.
  - errCode and errorDescription are returned.

A threeD class containing the 3DS authentication result response returned from the issuer which includes these parameters (if applicable):
- challengePreferenceReason – The challenge/exemption reason decided by the issuer.
  - See the Challenge Preference Reasons table.
  - (The issuer’s decision can be based on a request from the merchant or based on their own risk calculations.
    See the 3DS Scenarios table for more details.)
- threeDReasonId – The failed 3DS authorization reason.
  - See the Failed 3DS Authorization Reason table.
For more details see the First Call 3DS Response Parameters section in the threeD Output Class topic.
For an example, see the Example /payment Response to a Challenge Request.

4. 3DS Challenge

For instructions on implementing the authentication challenge, see 3DS Authentication Challenge.

5. Final Payment Request

This step handles the response from the 3DS Challenge.

For a description of the 3DS authentication response returned by the issuer, see the 3DS Responses topic, which also describes the relevant 3DS challenge or exemption with their Challenge Preference Reasons.

Perform the next relevant step based on the outcome of the 3DS Challenge:

If the customer did not complete the challenge successfully, then the process ends here.
CRes would contain: transStatus: “N“.
If the customer completed the challenge successfully, then:
CRes would contain: transStatus: “Y“.
Complete the payment process by sending a final Liability Shift Payment (3DS) request (see below).

Liability Shift – 3DS

If the 3DS challenge was successful, then complete the payment process by sending another /payment request with its mandatory parameters and include these additional parameters:

Include relatedTransactionId. Specify the transactionId from the response to the first /payment request in this step.
Do not include the 3DS class.

Example Liability Shift `/payment` (3DS) Request

{
    "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>",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"CL-BRW1",
            "expirationMonth":"12",
            "expirationYear":"22",
            "CVV":"217"
        }
    },
    "relatedTransactionId":"<transactionId returned from previous payment request>",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "country":"US",
        "email":"[email protected]"
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.nuvei.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in your system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
        ],
    'relatedTransactionId' => '<paymentTransactionId>', //as returned from 1st payment call
    'billingAddress' => [
        'firstName'  => "John",
        'lastName'   => "Smith",
        'country'    => 'US',
        'email'      => '[email protected]',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '<customer's IP address>',
    ],
]);
?>

//Initialize the SDK (see https://docs.nuvei.com/?p=29433)
{
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "<paymentTransactionId>";  // transactionId returned from previous payment request

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("CL-BRW1");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setCVV("217");

    paymentOption.setCard(card);

    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    deviceDetails.setIpAddress("<customer's IP address>");

    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, relatedTransactionId, null, null, null, null, null, null, null, null);
}

//Initialize the SDK (see https://docs.nuvei.com/?p=48413)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "<paymentTransactionId>", // transactionId returned from previous payment request
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

//Initialize the SDK (see https://docs.nuvei.com/?p=53443)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    paymentOption  : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217"
    },
    relatedTransactionId : "<paymentTransactionId>", // transactionId returned from previous payment request
    billingAddress : {
        firstName : "John",
        lastName  : "Smith",
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Example Liability Shift `/payment` (3DS) Response

{
    "orderId": "277063039",
    "paymentOption": {
        "userPaymentOptionId": "",
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "22",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "threeD": {
                "eci": "5",
                "version": "2.1.0",
                "whiteListStatus": "N",
                "cavv": "dHdQMm40SFVwU3BLWEFqR3JVaVc=",
                "result": "Y",
                "acsTransId": "322fdcfc-e39d-43e3-80b8-3b9c4a47e404",
                "dsTransID": "deaa2f1c-3957-4b66-9192-d6665a4508e5",
                "threeDReasonId": "",
                "challengeCancelReasonId": "",
                "challengeCancelReason": "",
                "isLiabilityOnIssuer": "1",
                "challengePreferenceReason": "12"
            }
        }
    },
    "transactionStatus": "APPROVED",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionType": "Sale",
    "transactionId": "1110000000011303477",
    "externalTransactionId": "",
    "authCode": "111511",
    "customData": "",
    "fraudDetails": {
        "finalDecision": "Accept"
    },
    "sessionToken": "3b44eb34-f94f-4e67-b268-2c67d24dd861",
    "internalRequestId": 235073239,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20210126124931"
}

REST 1.0

1. Authentication

Sending a /getSessionToken

Example /getSessionToken Request

Example /getSessionToken Response

2. Initialize 3DS

Example /initPayment Request

Example /initPayment Response – v2supported: “true”

Example /initPayment Response – v2supported: “false”

Handling the /initPayment Response