Zero-Authorization

Home    Online Payments    Card Operations    Zero-Authorization

On this page:

Overview

A merchant may want to perform a zero-authorization card transaction in order to:

  • Store card details for future use – Card schemes often insist that a zero-authorization transaction be sent before allowing card credentials to be stored for future use.
  • Add a card (card registration) – A customer is sometimes required to add a card to their account so that it can be verified and used to charge the customer at a later date. For example, adding a card at the beginning of an evaluation period so it can be verified and charged at the end of the evaluation period.
  • Verify a card – A merchant may want to move a potential customer to the next stage in the sales cycle by asking them to supply their card details. This allows the merchant to verify the existence of a card without charging it as well as testing the customer’s level of commitment to eventually completing the sale.

The zero-authorization flows should be performed ONLY if a deposit is NOT performed during the same user session. Any deposit should be performed in a separate session.

A zero-authorization transaction can be performed:

  • With Web SDK
  • With REST API
  • For merchants with a low PCI level
  • For non-3DS tokenization
  • For non-3DS tokenization with a low PCI level

Zero-Auth with Web SDK

  1. Call the /openOrder API call and set amount=0 and transactionType=Auth.
    Example /openOrder API Call
    {  
    "merchantId":"<your merchantId goes here>",
    "merchantSiteId":"<your merchantSiteId goes here>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"0",
    "userTokenId": "<unique customer identifier in merchant system>",
    "transactionType": "Auth",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
    <?php
$safecharge = new \SafeCharge\Api\RestClient([
'environment' => \SafeCharge\Api\Environment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'clientUniqueId'    => '<unique transaction ID in merchant system>',
    'clientRequestId'   => '<unique request ID in merchant system>',
    'currency'          => 'USD',
    'amount'            => '0',
    'userTokenId'       => '<unique customer identifier in merchant system>',
    'transactionType' => 'Auth',
]);
?>
    public static void main(String[] args) {
// for initialization 
String merchantId = "<your merchantId>";
String merchantSiteId = "<your merchantSiteId>";
String merchantKey = "<your merchantKey>"; safecharge.initialize(merchantId, merchantSiteId, merchantKey, 
APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);

//for openOrder
String userTokenId = "<unique customer identifier in merchant system>";
String clientUniqueId = "<unique transaction ID in merchant system>";
String clientRequestId = "<unique request ID in merchant system>";
String currency = "USD";
String amount = "0";
String transactionType = "Auth";

Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, 
null, null, null, null, null, null, null, null, null, null, null, null, 
null, null, null, null, null, null);
}
    var safecharge = new Safecharge(
"<your merchantKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value>",
HashAlgorithmType.SHA256
);
var response = safecharge.OpenOrder(
 "USD",
 "0",
 transactionType: "Auth",
 userTokenId: "<unique customer identifier in merchant system>",
 clientUniqueId: "<Transaction ID in your system>",
 clientRequestId: "<unique request ID in merchant system>",
);
    const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
safecharge.paymentService.openOrder({
    'clientUniqueId'   : '<unique transaction ID in merchant system>',
    'clientRequestId'  : '<unique request ID in merchant system>',
    'currency'         : 'USD',
    'amount'           : '0'
    'transactionType' : 'Auth',
    'userTokenId' : '230811147',
}, function (err, result) {
    console.log(err, result)
});
  2. Use a createPayment()  call to send an authorization-only request.
    Example createPayment() Request
    sfc.createPayment({
    sessionToken: "3993eb0c-5f64-4a6c-b16c-485818eb76eb", //received from openOrder API 
    merchantId: "<your merchantId>", //as assigned by Nuvei
    merchantSiteId: "<merchantSiteId>", //as assigned by Nuvei
    clientUniqueId: "<unique transaction ID in merchant system>", // optional
    paymentOption: {
      card: { //this sample clearly shows text cards can also work with Nuvei Fields
        cardNumber: "5111426646345761",
        cardHolderName: "John Smith",
        expirationMonth: "12",
        expirationYear: "2030",
        CVV: "217"
      }
    }
  },
  function(res) {
    console.log(res) if (res.cancelled === true) {
      example.querySelector('.token').innerText = 'cancelled';
    }
    else {
      example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId;
    }
    example.classList.add('submitted');
  }
)
  3. Perform a full 3D Secure (3DS) challenge to comply with the “strong authentication validation” requirement set by card schemes for each zero-authorization request.

Zero-Auth with REST API

  1. Call the /getSessionToken method.
    Example /getSessionToken Request
    {
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
    $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. Initialize the payment in the Nuvei system by sending an /initPayment request and setting amount=0 and transactionType=Auth.
    Example /initPayment Request
    {
    "sessionToken": "<sessionToken from /getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientRequestId": "<unique request ID in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "USD",
    "amount": "0",
    "transactionType": "Auth",
    "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'         => '0',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'transactionType' => 'Auth',
    '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 merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";

    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, transactionType, deviceDetails, initPaymentOption, null, null, null);
}
    var response = safecharge.InitPayment(
    "USD",
    "0",
    new InitPaymentOption
    {
        Card = new InitPaymentCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new InitPaymentThreeD
            {
                MethodNotificationUrl = "<MethodNotificationUrl>",
            }
        }
    },
    transactionType: "Auth",
    userTokenId: "<unique customer identifier in merchant system>",
    orderId: "33704071",
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<<unique request ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });
    safecharge.paymentService.initPayment({
    userTokenId            : "<unique customer identifier in merchant system>",
    clientRequestId        : "<unique request ID in merchant system>",
    clientUniqueId         : "<unique transaction ID in merchant system>",
    amount                 : "0",
    currency               : "USD",
    transactionType        : "Auth",
    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);
});
  3. Perform a full 3DS challenge using a /payment API call to send an authorization-only request with the following requirements:
    • Set amount=0
    • Set transactionType=Auth
    • Include authenticationOnlyType (press here for possible values).

    (See the 3DS Payment topic and continue from there to follow a 3DS challenge flow.)

    Example /payment API Request (for 3DS)
    {
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"0",
    "currency":"USD",
    "transactionType":"Auth",
    "authenticationOnlyType": "ADDCARD",
    "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":"<initPaymentTransactionId>",
    "billingAddress":{
        "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'         => '0',
    'transactionType' => 'Auth',
    'authenticationOnlyType' => 'ADDCARD',
    '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' =>[
                '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'                => '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', //as returned from initPayment
    'billingAddress' => [
        '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 = "0";
    String transactionType = "Auth";
    String authenticationOnlyType = "ADDCARD";

    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.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, transactionType, authenticationOnlyType, 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",
    "0",
    new PaymentOption
    {
        Card = new Card
        {
            ccTempToken = "<as returned by getToken method>",
            CardHolderName = "CL-BRW1",
            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)"
                }
            }
        }
    },
    transactionType: "Auth",
    authenticationOnlyType: "ADDCARD",
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "initPaymentTransactionId", // as returned from initPayment
    billingAddress: new UserAddress
    {
        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         : "0",
    transactionType : "Auth",
    authenticationOnlyType: "ADDCARD",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    paymentOption  : {
        card : {
            ccTempToken : "<as returned by getToken method>",
            cardHolderName  : "john smith",
            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", //as returned from initPayment
    billingAddress : {
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Zero-Auth for Merchants with a Low PCI Level

This flow is a combination of using REST API and Web SDK and is used for tokenization by merchants without a sufficient PCI level.

  1. Call the /getSessionToken method.
    Example /getSessionToken Request
    {
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
    $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. Call the getToken() Web SDK method.
    Example getToken() Request
    sfc.getToken(scard).then(function(result) {
        cardHolderName: 'john smith'
        if (result.status === 'SUCCESS') {
             console.log(result.paymentOption) //pass the paymentOption to the payment API call
        } else {
            // handle error.

        }
    });
  3. Initialize the payment in the Nuvei system by sending an /initPayment REST API method and setting amount=0 and transactionType=Auth.
    Be sure to include the ccTempToken retrieved from the Web SDK getToken response.
    Example /initPayment Request
    {
    "sessionToken": "<sessionToken from /getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientRequestId": "<unique request ID in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "USD",
    "amount": "0",
    "transactionType": "Auth",
    "paymentOption": {
        "card": {
            "ccTempToken":"<as returned by getToken method>",
            "cardHolderName": "CL-BRW1",
            "threeD": {
                "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    }
}
    <?php
//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    'currency'       => 'USD',
    'amount'         => '0',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'transactionType' => 'Auth',
    'clientRequestId' => '<unique request ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'ccTempToken' => '<as returned by getToken method>',
            'cardHolderName'  => 'CL-BRW1',
            'threeD' =>[
                'methodNotificationUrl'=>'<methodNotificationURL>',
            ]
        ]
    ],
    'deviceDetails'     => [
        "ipAddress"  => "<customer's IP address>"
    ],
]);
?>
    {
    // Parameters needed for initPayment call
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";

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

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

    InitPaymentCard card = new InitPaymentCard();
    card.setccTempToken("<ccTempToken as returned by getToken method>");
    card.setCardHolderName("CL-BRW1");
    card.setThreeD(threeD);

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

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.initPayment(userTokenId, clientUniqueId, clientRequestId, currency, amount, transactionType, deviceDetails, initPaymentOption, null, null, null);
}
    var response = safecharge.InitPayment(
    "USD",
    "0",
    new InitPaymentOption
    {
        Card = new InitPaymentCard
        {
            ccTempToken = "<ccTempToken as returned by getToken method>",
            CardHolderName = "CL-BRW1",
            ThreeD = new InitPaymentThreeD
            {
                MethodNotificationUrl = "<MethodNotificationUrl>",
            }
        }
    },
    transactionType: "Auth",
    userTokenId: "<unique customer identifier in merchant system>",
    orderId: "33704071",
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<<unique request ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });
    safecharge.paymentService.initPayment({
    userTokenId            : "<unique customer identifier in merchant system>",
    clientRequestId        : "<unique request ID in merchant system>",
    clientUniqueId         : "<unique transaction ID in merchant system>",
    amount                 : "0",
    currency               : "USD",
    transactionType        : "Auth",
    paymentOption  : {
        card: {
            ccTempToken : "<as returned by getToken method>",
            cardHolderName : "CL-BRW1",
            threeD :{
                methodNotificationUrl : "<methodNotificationUrl>"
            }
        }
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});
  4. Perform a full 3DS challenge using a /payment API call to send an authorization-only request with the following requirements:
    • Set amount=0
    • Set transactionType=Auth
    • Include authenticationOnlyType (press here for possible values).

    (See the 3DS Payment topic and continue from there to follow a 3DS challenge flow.)

    Example /payment Request (for 3DS)
    {
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"0",
    "currency":"USD",
    "transactionType":"Auth",
    "authenticationOnlyType": "ADDCARD",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "card":{
            "ccTempToken":"<as returned by getToken method>",
            "cardHolderName": "CL-BRW1",
            "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":"<initPaymentTransactionId>",
    "billingAddress":{
        "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'         => '0',
    'transactionType' => 'Auth',
    'authenticationOnlyType' => 'ADDCARD',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'ccTempToken' => '<as returned by getToken method>',
            'cardHolderName'  => 'CL-BRW1',
            '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', //as returned from initPayment
    'billingAddress' => [
        '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 = "0";
    String transactionType = "Auth";
    String authenticationOnlyType = "ADDCARD";

    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.setccTempToken("<as returned by getToken method>");
    card.setCardHolderName("CL-BRW1");

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

    UserAddress billingAddress = new UserAddress();
    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, transactionType, 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",
    "0",
    new PaymentOption
    {
        Card = new Card
        {
            ccTempToken = "<as returned by getToken method>",
            CardHolderName = "CL-BRW1",
            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)"
                }
            }
        }
    },
    transactionType: "Auth",
    authenticationOnlyType: "ADDCARD",
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "initPaymentTransactionId", // as returned from initPayment
    billingAddress: new UserAddress
    {
        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         : "0",
    transactionType : "Auth",
    authenticationOnlyType: "ADDCARD",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    paymentOption  : {
        card : {
            ccTempToken : "<as returned by getToken method>",
            cardHolderName  : "CL-BRW1",
            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                : "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", //as returned from initPayment
    billingAddress : {
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Zero-Auth for Non-3DS Tokenization

This flow triggers non-3DS tokenization and should be used for traffic outside PSD2 regulations.

  1. Call the /getSessionToken method.
    Example /getSessionToken Request
    {
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
    $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. Use the /payment REST API method to send an authorization-only request with the following requirements:
    • Set amount=0
    • Set transactionType=Auth
    • Include authenticationOnlyType (press here for possible values).
    Example /payment API Request
    {
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"0",
    "currency":"USD",
    "transactionType":"Auth",
    "authenticationOnlyType": "ADDCARD",
    "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"
        }
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "billingAddress":{
        "email":"[email protected]",
        "country":"US"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
    //Initialize the SDK see https://docs.nuvei.com/?p=53233

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '0',
    'transactionType' => 'Auth',
    'authenticationOnlyType' => 'ADDCARD',
    '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',
        ]
    ],
    'billingAddress' => [
        'country'   => "US",
        "email"     => "[email protected]",
    ],
    'deviceDetails'  => [
        "ipAddress"  => "<customer's IP address>",
    ],
]);
?>
    //Initialize the SDK see https://docs.nuvei.com/?p=29433

{
    // Parameters needed for payment simple card call
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";
    String authenticationOnlyType = "ADDCARD";

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

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

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

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

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId,
    clientRequestId, paymentOption, transactionType, currency, amount, null, null,
    deviceDetails, null, null, billingAddress, 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",
    "0",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    transactionType: "Auth",
    authenticationOnlyType: "ADDCARD",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    clientUniqueId: "<unique transaction ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });
    //Initialize the SDK see https://docs.nuvei.com/?p=53443

safecharge.paymentService.createPayment({
    amount       : "0",
    currency     : "USD",
    transactionType : "Auth",
    authenticationOnlyType: "ADDCARD",
    sessionToken : "<sessionToken from /openOrder>",
    paymentOption: {
        card: {
            expirationYear : "2030",
            CVV            : "217",
            cardHolderName : "John Smith",
            expirationMonth: "12",
            cardNumber     : "4000027891380961"
        }
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

Zero-Auth for Non-3DS Tokenization with a Low PCI Level

This flow triggers non-3DS tokenization and should be used for traffic outside PSD2 regulations.

This flow is a combination of using REST API and Web SDK and is used for tokenization by merchants without a sufficient PCI level.

  1. Call the /getSessionToken method.
    Example /getSessionToken Request
    {
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
    $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. Call the getToken() Web SDK method.
    Example getToken() Request
    sfc.getToken(scard).then(function(result) {

        if (result.status === 'SUCCESS') {
             console.log(result.paymentOption) //pass the paymentOption to the payment API call
        } else {
            // handle error.

        }
    });
  3. Use the /payment REST API method to send an authorization-only request with the following requirements:
    • Set amount=0
    • Set transactionType=Auth
    • Include authenticationOnlyType (press here for possible values).
    • Include the ccTempToken retrieved from the Web SDK getToken response.
Example /payment API Request
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"0",
    "currency":"USD",
    "transactionType":"Auth",
    "authenticationOnlyType": "ADDCARD",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{ 
        "card":{ 
            "ccTempToken":"<as returned by getToken method>",
            "cardHolderName":"CL-BRW1"
        }
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "billingAddress":{
        "email":"[email protected]",
        "country":"US"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
//Initialize the SDK see https://docs.nuvei.com/?p=53233

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '0',
    'transactionType' => 'Auth',
    'authenticationOnlyType' => 'ADDCARD',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'ccTempToken' => '<as returned by getToken method>',
            'cardHolderName' => 'CL-BRW1',
        ]
    ],
    'billingAddress' => [
        'country'   => "US",
        "email"     => "[email protected]",
    ],
    'deviceDetails'  => [
        "ipAddress"  => "<customer's IP address>",
    ],
]);
?>
//Initialize the SDK see https://docs.nuvei.com/?p=29433

{
    // Parameters needed for payment simple card call
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";
    String authenticationOnlyType = "ADDCARD";

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

    Card card = new Card();
    card.setccTempToken("<as returned by getToken method>");
    card.setCardHolderName("CL-BRW1");

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

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

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId,
    clientRequestId, paymentOption, transactionType, currency, amount, null, null,
    deviceDetails, null, null, billingAddress, 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",
    "0",
    new PaymentOption
    {
        Card = new Card
        {
            ccTempToken = "<as returned by getToken method>",
            CardHolderName = "CL-BRW1"
        }
    },
    transactionType: "Auth",
    authenticationOnlyType: "ADDCARD",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    clientUniqueId: "<unique transaction ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });
//Initialize the SDK see https://docs.nuvei.com/?p=53443

safecharge.paymentService.createPayment({
    amount       : "0",
    currency     : "USD",
    transactionType : "Auth",
    authenticationOnlyType: "ADDCARD",
    sessionToken : "<sessionToken from /openOrder>",
    paymentOption: {
        card: {
            ccTempToken : "<as returned by getToken method>",
            cardHolderName : "CL-BRW1"
        }
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

Appendix

Possible Values for authenticationOnlyType

ValueDescriptionNotes
RECURRINGFor when multiple transactions are submitted by the Merchant separately based on an agreement between the Merchant and the cardholder.For example: A gym subscription in which the cardholder is charged $40 per month.
Typically the first transaction is a CIT and all the rest are MITs.
Each transaction has its own authorization and clearing.
Charges are stopped only if the agreement between the merchant and the cardholder is terminated.
INSTALLMENTSFor when a single transaction is divided into multiple charges.There is one authorization for the full amount and a clearing per installment. Charges are stopped when the full amount is charged.
ADDCARDFor when a cardholder adds their card to be used for future transactions.For example: Adding a card to a ride-sharing service for future rides.
MAINTAINCARDFor when a Merchant wants to verify that an existing card is still valid.
ACCOUNTVERIFICATIONFor a verification different than those listed above.
Last update iconLast modified February 2025