Overview
Accepting customer payments using the two-step Auth-Settle flow in Nuvei’s server-side REST environment, allows you to perform the Authorization and the Settle as separate steps.
- Authorization Step
Request the issuer (bank) to pre-authorize the “availability” of the purchase amount in their customer’s account. - Settle Step
After receiving approval from the issuer (bank) you can do one of the following:- Debit the customer’s card by sending a
/settleTransaction
request for full settlement of the authorized amount. - You can send multiple
/settleTransaction
requests as partial payments, which add up to the original authorized purchaseamount
. - For merchants with an American
merchantId
who use a TSYS bank as the acquirer, you can send multiple partial settle transactions totaling the full amount, as described in the Multi-Settle Option topic below.
- Debit the customer’s card by sending a
This requests the issuer (bank) to pre-authorize the “availability” of the purchase amount in their customer’s account. Send a If the issuer (bank) approves the request, then they return an Next step, perform one of the following: After receiving approval from the issuer (bank) you can do one of the following: The You can send one or multiple Send one or more The Multi-Settle is an optional feature that allows multiple partial settle transactions, totaling the full amount. Send a Authorization Step
/payment
request with its mandatory parameters and include these parameters:
transactionType
parameters:
transactionType
: “Auth”
Auth
transaction places a temporary hold on the approved amount
in the customer’s account for a short time frame to ensure sufficient funds to settle the payment.
Later, when the product is ready for shipping, they can finalize the purchase by sending a /settleTransaction
request to debit/charge the card.transactionType
: “PreAuth”
PreAuth
is similar to the Auth
request, but upon approval from the bank, the temporary hold can be placed on an amount larger than the “final purchase amount”, and the hold can be set for a longer time frame.
When the car is returned without fines, scratches, or accident damage, you can send a /settleTransaction
request ($400) to debit/charge the card and remove the temporary hold.Example
/payment
Request with transactionType
: “Auth”{
"sessionToken":"<sessionToken from /getSessionToken>",
"merchantId":"<your merchantId>",
"merchantSiteId":"<your merchantSiteId>",
"clientRequestId":"<unique request ID in merchant system>",
"amount":"200",
"currency":"USD",
"transactionType":"Auth",
"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":"john.smith@email.com",
"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' => '100',
'transactionType' => 'Auth',
'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" => "john.smith@email.com",
],
'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 = "100";
String transactionType = "Auth";
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("john.smith@email.com");
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",
"100",
new PaymentOption
{
Card = new Card
{
CardNumber = "4000027891380961",
CardHolderName = "John Smith",
ExpirationMonth = "12",
ExpirationYear = "22",
CVV = "217"
}
},
transactionType: "Auth",
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 : "100",
currency : "USD",
transactionType : "Auth",
sessionToken : "<sessionToken from /getSessionToken>",
paymentOption: {
card: {
expirationYear : "2030",
CVV : "217",
cardHolderName : "John Smith",
expirationMonth: "12",
cardNumber : "4000027891380961"
}
},
}, function (pErr, pResult) {
console.log(pErr, pResult);
});
Response from the
/payment
RequestauthCode
in the response from the /payment
request. In order to ensure sufficient funds for settling the payment, the issuer (bank) places a temporary hold on funds in the customer’s account, for the value of the approved amount
.
authCode
in a /settleTransaction
request, described in the Settle Step topic below./voidTransaction
request.Settle Step
/settleTransaction
request as full settlement of the authorized amount./settleTransaction
requests as partial payments, which add up to the original authorized purchase amount
.merchantId
who use a TSYS bank as the acquirer, you can send multiple partial settle transactions totaling the full amount, as described in the Multi-Settle Option topic below.
Sending a
/settleTransaction
Request/settleTransaction
method is used to perform a full or partial settlement of an approved authorization or pre-authorization./settleTransaction
requests, until the total of all the partial amounts
equals the original authorized amount
./settleTransaction
requests with its mandatory parameters and include these additional parameters:
relatedTransactionId
: “<transactionId
of the original Auth transaction>“authCode
– Returned in the response from the original /payment
request.currency
must match the currency
of the original authentication transaction.Example
/settleTransaction
Request{
"merchantId": "<your merchantId>",
"merchantSiteId": "<your merchantSiteId>",
"clientRequestId": "<unique request ID in merchant system>",
"clientUniqueId": "<unique transaction ID in merchant system>",
"amount": "200",
"currency": "USD",
"relatedTransactionId": "<transactionId of the original Auth transaction>",
"timeStamp": "<YYYYMMDDHHmmss>",
"checksum": "<calculated checksum>"
}
//Initialize the SDK see https://docs.nuvei.com/?p=53233
<?php
//settleTransaction
$settleResponse = $safeCharge->getPaymentService()->settleTransaction([
'clientUniqueId' => '<unique transaction ID in merchant system>',
'clientRequestId' => '<unique request ID in merchant system>',
'amount' => '200',
'currency' => 'USD',
'relatedTransactionId' => '<transactionId of the original Auth transaction>',
]);
?>
//Initialize the SDK see https://docs.nuvei.com/?p=29433
{
String clientUniqueId = "<unique transaction ID in merchant system>";
String clientRequestId = "<unique request ID in merchant system>";
String currency = "USD";
String amount = "200";
String relatedTransactionId = "<transactionId of the original Auth transaction>";
Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.settleTransaction(clientUniqueId, null, null,
null, null, null, amount, null, null, null, currency, null, null, relatedTransactionId, null);
}
//Initialize the SDK see https://docs.nuvei.com/?p=48413
var response = safecharge.SettleTransaction(
"USD",
"200",
relatedTransactionId: "<transactionId of the original Auth transaction>",
clientRequestId: "<unique request ID in merchant system>",
clientUniqueId: "<unique transaction ID in merchant system>");
//Initialize the SDK see https://docs.nuvei.com/?p=53443
safecharge.paymentService.settleTransaction({
clientUniqueId : "<unique transaction ID in merchant system>",
amount : "200",
currency : "USD",
relatedTransactionId : "<transactionId of the original Auth transaction>",
}, function (stlErr, stlRes) {
console.log(stlErr, stlRes);
});
Example
/settleTransaction
Response{
"transactionId": "1110000000004320882",
"externalTransactionId": "",
"gwErrorCode": 0,
"gwExtendedErrorCode": 0,
"transactionStatus": "APPROVED",
"authCode": "111570",
"clientUniqueId": "20200307174645",
"CVV2Reply": "",
"AVSCode": "",
"transactionType": "Settle",
"customData": "",
"acquirerId": "19",
"bin": "400002",
"last4Digits": "2535",
"ccCardNumber": "4****2535",
"ccExpMonth": "09",
"ccExpYear": "21",
"cardType": "Credit",
"cardBrand": "VISA",
"whiteListStatus": "",
"cavv": "",
"serverTransId": "",
"threeDresult": "",
"acsTransId": "",
"dsTransID": "",
"internalRequestId": 178720588,
"status": "SUCCESS",
"errCode": 0,
"reason": "",
"merchantId": "4960497427404081578",
"merchantSiteId": "197846",
"version": "1.0",
"clientRequestId": "1C6CT7V1L"
}
Multi-Settle Option
/settleTransaction
request with its mandatory parameters and include these additional parameters:
totalSettleCount
: “<number (a positive integer) of settlements into which the settlement is split>”
totalSettleCount
must be included in the first /settleTransaction
request.totalSettleCount
must be included in all subsequent /settleTransaction
requests, and the value must be the same as in the first request.relatedTransactionId
: “<transactionId of the original authentication transaction>“authCode
– Returned in the response from the original /payment
request.currency
must match the currency
of the original authentication transaction.Example
/settleTransaction
Request{
"merchantId": "<your merchantId>",
"merchantSiteId": "<your merchantSiteId>",
"clientRequestId": "<unique request ID in merchant system>",
"clientUniqueId": "<unique transaction ID in merchant system>",
"amount": "200",
"currency": "USD",
"relatedTransactionId": "<transactionId of the original Auth transaction>",
"authCode": "622190",
"totalSettleCount": "2",
"timeStamp": "<YYYYMMDDHHmmss>",
"checksum": "<calculated checksum>"
}
Example
/settleTransaction
Response{
"reason":"",
"ccCardNumber":"5****4531",
"bin":"547268",
"ccExpYear":"25",
"customData":"",
"merchantSiteId":"126006",
"gwExtendedErrorCode":0,
"isPrepaid":"false",
"merchantId":"2502136204546424962",
"externalTransactionId":"",
"acquirerId":"99",
"cardBrand":"MASTERCARD",
"issuerBankName":"DEUTSCHE BANK AG ",
"authCode":"622190",
"transactionStatus":"APPROVED",
"clientRequestId":"XI2JDDE4Z",
"cardType":"Credit",
"ccExpMonth":"12",
"internalRequestId":19706991,
"AVSCode":"",
"version":"1.0",
"transactionId":"2110000000005751343",
"CVV2Reply":"",
"transactionType":"Settle",
"issuerCountry":"DE",
"gwErrorCode":0,
"clientUniqueId":"SHCUOEBONIGG",
"errCode":0,
"last4Digits":"4531",
"status":"SUCCESS"
}