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:

1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
   merchantId, merchantSiteId,clientRequestId,timeStamp, merchantSecretKey
2. 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"
}

Initializing SafeCharge() Object

To generate a sessionToken, you can initialize the SafeCharge() object, as shown below:

Example Initializing the SafeCharge() Object

$safecharge = new SafeChargeApiRestClient([
'environment' => SafeChargeApiEnvironment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

public class Main {
    public static void main(String[] args) {
        String merchantId = "<your merchantId>";
        String merchantSiteId = "<your merchantSiteId>";
        String merchantKey = "<your merchantKey>";

            safecharge.initialize(merchantId, merchantSiteId, merchantKey, Constants.HashAlgorithm.SHA256);
    }
}

var safecharge = new Safecharge(
"<your merchantKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value>",
HashAlgorithmType.SHA256
);

const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);

2. Render a Payment Form

Render a form to collect the cardholder details on your payment page.

3. Initialize 3D-Secure

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:

• 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) For 3D-Secure v2 only, if you intend to perform 3D-Secure 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 3D-Secure v2.
    However, you can still send a Non-3DS payment (without liability shift).
  • 3D-Secure v2
    If threeD.v2supported:”true“, then the card supports 3D-Secure v2.

4. Payment

Process the payment according to the relevant card authentication flow:

• Non-3DS (without liability shift)
  
• 3D-Secure v2

Non-3D-Secure 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"
}

3D-Secure v2 Payment

Follow the steps below to perform a 3D-Secure v2 payment.

To perform a 3D-Secure v2 payment, send a /payment request with its mandatory parameters and include these additional parameters:

• The threeD Input Class paymentOption.card.threeD containing the 3D-Secure v2 parameters:
  • If 3D-Secure Fingerprinting was performed, then set the value of paymentOption.card.threeD.methodCompletionInd to the value returned.
  • If 3D-Secure 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 3D-Secure challenge step. This URL is needed for the next step (3D-Secure Challenge).
  • version – The 3D-Secure v2.x version supported by the card (returned in the response to the /initPayment request).
  • challengePreference (optional) – The merchant’s challenge/exemption preference for each transaction, sent to the issuer during the 3DS v2 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 3D-Secure v2

{
    "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 3D 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 3D 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 3D-Secure v2

{
    "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 3D-Secure 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 3D-Secure program.
      The process ends here.

    • For 3D-Secure v2 – If you requested a 3D-Secure Exemption, the issuer has approved a non-3D 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 3D-Secure 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 3D-Secure Response Parameters section in the threeD Output Class topic.
  For an example, see the Example /payment Response to a Challenge Request.

5. 3D-Secure Challenge

For instructions on implementing the authentication challenge, see 3D-Secure Authentication Challenge.

6. Final Payment Request

Perform the next relevant step based on the outcome of the 3D-Secure Challenge:

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

Liability Shift – 3D-Secure v2

If the 3D-Secure v2 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 Step 4.
• Do not include the 3D-Secure class.

Example Liability Shift /payment (3D-Secure v2) 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 (3D-Secure v2) 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"
}