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:
- With Web SDK
- With REST API
- For merchants with a low PCI level
- For non-3D tokenization
- For non-3D tokenization with a low PCI level
Zero-Auth with Web SDK
- Call the
/openOrder
API call and setamount
=0 andtransactionType
=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) });
- Use a
createPayment()
call to send an authorization-only request.
Example
createPayment()
Requestsfc.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'); } )
- Perform a full 3D-Secure challenge to comply with the “strong authentication validation” requirement set by card schemes for each zero-authorization request.
Zero-Auth with REST API
- 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>);
- Initialize the payment in the Nuvei system by sending an
/initPayment
request and settingamount
=0 andtransactionType
=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); });
- Perform a full 3D-Secure 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 3D-Secure v2 Payment topic and continue from there to follow a 3D-Secure challenge flow.)
Example
/payment
API Request (for 3D-Secure v2){ "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 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' => '[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 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 : "[email protected]" }, deviceDetails : { ipAddress : "<customer's IP address>" }, }, function (pErr, pResult) { console.log(pErr, pResult) });
- Set
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.
- 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>);
- Call the
getToken()
Web SDK method.
Example
getToken()
Requestsfc.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. } });
- Initialize the payment in the Nuvei system by sending an
/initPayment
REST API method and settingamount
=0 andtransactionType
=Auth.
Be sure to include theccTempToken
retrieved from the Web SDKgetToken
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); });
- Perform a full 3D-Secure 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 3D-Secure v2 Payment topic and continue from there to follow a 3D-Secure challenge flow.)
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":"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 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' => '[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 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 : "[email protected]" }, deviceDetails : { ipAddress : "<customer's IP address>" }, }, function (pErr, pResult) { console.log(pErr, pResult) });
- Set
Zero-Auth for Non-3D Tokenization
This flow triggers non-3D tokenization and should be used for traffic outside PSD2 regulations.
- 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>);
- 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); });
- Set
Zero-Auth for Non-3D Tokenization with a Low PCI Level
This flow triggers non-3D 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.
- 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>);
- Call the
getToken()
Web SDK method.
Example
getToken()
Requestsfc.getToken(scard).then(function(result) { if (result.status === 'SUCCESS') { console.log(result.paymentOption) //pass the paymentOption to the payment API call } else { // handle error. } });
- 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 SDKgetToken
response.
- Set
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
Value | Description | Notes |
---|---|---|
RECURRING | For 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. |
INSTALLMENTS | For 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. |
ADDCARD | For 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. |
MAINTAINCARD | For when a Merchant wants to verify that an existing card is still valid. | |
ACCOUNTVERIFICATION | For a verification different than those listed above. |