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.

A zero-authorization transaction can be performed in two ways:

  • Using Web SDK
  • Using REST API

Using Web SDK

  1. Call the /openOrder API call and set amount=0 and transactionType=Auth.
    Example of an /openOrder API Call 
    {  
    "merchantId":"<your merchantId goes here>",
    "merchantSiteId":"<your merchantSiteId goes here>",
    "clientUniqueId":"<The ID of the transaction in the merchant's system>",
    "clientRequestId":"<The ID of the API request in the merchant’s system>",
    "currency":"USD",
    "amount":"0",
    "userTokenId": "<a user identifier>",
    "transactionType": "Auth",
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
    <?php
$safecharge = new \SafeCharge\Api\RestClient([
'environment' => \SafeCharge\Api\Environment::TEST,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'clientUniqueId'    => '<The ID of the transaction in the merchant's system>',
    'clientRequestId'   => '<The ID of the API request in the merchant’s system>',
    'currency'          => 'USD',
    'amount'            => '0',
    'userTokenId'       => '<a user identifier>',
    'transactionType' => 'Auth',
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
]);
?>
    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, Constants.HashAlgorithm.SHA256);

//for openOrder
String userTokenId = "<a user identifier>";
String clientUniqueId = "<The ID of the transaction in the merchant's system>";
String clientRequestId = "<The ID of the API request in the merchant’s system>";
String currency = "USD";
String amount = "0";
String transactionType = "Auth";

UserAddress billingAddress = new UserAddress();
billingAddress.setEmail("john.smith@email.com");
billingAddress.setCountry("US");

Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
clientUniqueId, null, null, null, transactionType, currency, amount,
null, null, null, null, billingAddress, 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: "<a user identifier>",
 clientUniqueId: "<The ID of the transaction in the merchant's system>",
 clientRequestId: "<The ID of the API request in the merchant’s system>",
 billingAddress: new UserAddress
 {
     Email = "john.smith@email.com",
     Country = "US",
 }
);
    const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
safecharge.paymentService.openOrder({
    'clientUniqueId'   : '<The ID of the transaction in the merchant's system>',
    'clientRequestId'  : '<The ID of the API request in the merchant’s system>',
    'currency'         : 'USD',
    'amount'           : '0'
    'transactionType' : 'Auth',
    'userTokenId' : '230811147',
    'billingAddress': {
        'email': "john.smith@email.com",
        'country': "US"
    },
}, 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": "<The ID of the transaction in the merchant's system>", // optional
    "paymentOption": {
      "card": { //this sample clearly shows text cards can also work with Nuvei Fields
        "cardNumber": "5111426646345761",
        "cardHolderName": "John Smith",
        "expirationMonth": "12",
        "expirationYear": "2022",
        "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 challenge (see 3D-Secure Guide), to comply with the “strong authentication validation” requirement set by card schemes for each zero-authorization request.

Using REST API

  1. Call the /getSessionToken method.
    Example getSessionToken Request 
    {
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<The ID of the API request in the merchant’s system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
    $safecharge = new SafeChargeApiRestClient([
'environment' => SafeChargeApiEnvironment::TEST,
'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 set amount=0 and transactionType=Auth.
    Example initPayment Request 
    {
    "sessionToken": "<sessionToken from getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<a user identifier>",
    "clientRequestId": "<The ID of the API request in the merchant’s system>",
    "clientUniqueId": "<The ID of the transaction in the merchant's system>",
    "currency": "USD",
    "amount": "0",
    "transactionType": "Auth",
    "paymentOption": {
        "userPaymentOptionId": "<The ID of a previously stored payment option>",
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "CL-BRW1",
            "expirationMonth": "12",
            "expirationYear": "2022",
            "CVV": "217",
            "threeD": {
                "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    }
}
    <?php
//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    'currency'       => 'USD',
    'amount'         => '0',
    'userTokenId'    => '<a user identifier>',
    'transactionType' => 'Auth',
    'clientRequestId' => '<The ID of the API request in the merchant’s system>',
    'paymentOption'  => [
        'userPaymentOptionId' => '<The ID of a previously stored payment option>',
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'methodNotificationUrl'=>'<methodNotificationURL>',
				]
        ]
    ],
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],
]);
?>
    {
    // Parameters needed for initPayment call
    String userTokenId = "<a user identifier>";
    String clientUniqueId = "<The ID of the transaction in the merchant's system>";
    String clientRequestId = "<The ID of the API request in the merchant’s system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("127.0.0.1");

    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("2022");
    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: "<a user identifier>",
    orderId: "33704071",
    clientUniqueId: "<The ID of the transaction in the merchant's system>",
    clientRequestId: "<The ID of the API request in the merchant’s system>",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });
    safecharge.paymentService.initPayment({
    userTokenId            : "<a user identifier>",
    clientRequestId        : "<The ID of the API request in the merchant’s system>",
    clientUniqueId         : "<The ID of the transaction in the merchant's system>",
    amount                 : "0",
    currency               : "USD",
    transactionType        : "Auth",
    paymentOption  : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2022",
            CVV             : "217",
            threeD :{
                methodNotificationUrl : "<methodNotificationUrl>",
                }
        }
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});
  3. Use a /payment API call to send an authorization-only request. Make sure to set amount=0 and transactionType=Auth.
    Example /payment API Request (for 3D-Secure v2) 
    {
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<The ID of the API request in the merchant’s system>",
    "amount":"0",
    "currency":"USD",
    "transactionType":"Auth",
    "userTokenId":"<a user identifier>",
    "clientUniqueId":"<The ID of the transaction in the merchant's system>",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"CL-BRW1",
            "expirationMonth":"12",
            "expirationYear":"2022",
            "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":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '0',
    'transactionType' => 'Auth',
    'userTokenId'    => '<a user identifier>',
    'clientRequestId'=> '<The ID of the API request in the merchant’s system>"',
    'clientUniqueId'=> '<The ID of the transaction in the merchant's system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2022',
            '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', //as returned from initPayment
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>
    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

{
    String userTokenId = "<a user identifier>";
    String clientRequestId = "<The ID of the API request in the merchant’s system>";
    String clientUniqueId = "<The ID of the transaction in the merchant's system>";
    String currency = "USD";
    String amount = "0";
    String transactionType = "Auth";

    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("john.smith@email.com");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("127.0.0.1");

    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.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "0",
    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)"
                }
            }
        }
    },
    transactionType: "Auth",
    clientUniqueId: "<The ID of the transaction in the merchant's system>",
    clientRequestId: "<The ID of the API request in the merchant’s system>",
    userTokenId: "<a user identifier>",
    relatedTransactionId: "initPaymentTransactionId", // as returned from initPayment
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });
    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "0",
    transactionType : "Auth",
    userTokenId    : "<a user identifier>",
    clientUniqueId : "<The ID of the transaction in the merchant's system>",
    clientRequestId: "<The ID of the API request in the merchant’s system>",
    paymentOption  : {
        card : {
            cardNumber      : "CL-BRW1",
            cardHolderName  : "john smith",
            expirationMonth : "12",
            expirationYear  : "2022",
            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                : "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     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});