Auth and Settle

Home    Online Payments    Financial Operations    Auth and Settle

On this page:

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.

  1. Authorization Step
    Request the issuer (bank) to pre-authorize the “availability” of the purchase amount in their customer’s account.
  2. Settle Step
    After receiving approval from the issuer (bank) you can do one of the following:
    1. Debit the customer’s card by sending a /settleTransaction request for full settlement of the authorized amount.
    2. You can send multiple /settleTransaction requests as partial payments, which add up to the original authorized purchase amount.
    3. 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.

You can use Postman to run a full”Simple Auth-Settle scenario and Void” workflow simulation in the Nuvei sandbox environment.
To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

There is another way to accept customer payments using a one-step flow.

You can use the one-step “Sale” flow by sending a /payment request with transactionType: “Sale”, as described in the Server-to-Server topic.
(You can think of a Sale translation as a one-step Auth-Settle that combines authorization and settle back-to-back one transaction, which debits the customer’s card).

Authorization Step

This requests the issuer (bank) to pre-authorize the “availability” of the purchase amount in their customer’s account.

Send a /payment request with its mandatory parameters and include these parameters:

  • Include either of the following transactionType parameters:
    • transactionType: “Auth”
      • A successful 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.
      • At the end of the time frame, the authorization and the temporary hold expire automatically.
      • For example, a merchant wishing to charge their customer only after confirming product availability can send an authorization request.
        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.
      • The temporary hold is “cleared” when you charge the card for the purchase, or it “falls off” (expires) automatically after 7 to 31 days, depending on the issuer and the industry.
      • For example, a merchant (a car rental company for instance) can send a pre-authorization to temporarily hold a large amount ($5000) in the customer’s account.
        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":"[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'         => '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"     => "[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 = "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("[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",
    "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 Request

If the issuer (bank) approves the request, then they return an authCode 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.

Next step, perform one of the following:

Settle Step

After receiving approval from the issuer (bank) you can do one of the following:

  1. Debit the customer’s card by sending a /settleTransaction request as full settlement of the authorized amount.
  2. You can send multiple /settleTransaction requests as partial payments, which add up to the original authorized purchase amount.
  3. 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.

A /refundTransaction request can be used to refund a previously settled transaction.


Sending a /settleTransaction Request

The /settleTransaction method is used to perform a full or partial settlement of an approved authorization or pre-authorization.

You can send one or multiple /settleTransaction requests, until the total of all the partial amounts equals the original authorized amount.

It is also possible to configure an automatic delayed settle feature, which automatically settles authorization transactions based on time or a risk decision.
The minimum time frame is the “scheduler minimum interval”, which can be a few minutes.
For more information, please contact the Nuvei Integration Team.

Send one or more /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.
  • The 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

The Multi-Settle is an optional feature that allows multiple partial settle transactions, totaling the full amount.

  • This option is only relevant to merchants with an American merchantId, who use a TSYS bank as the acquirer.
  • The feature is supported by the following card schemes: Visa / Mastercard / Discover / JCB / Diners /CUP.
  • Amex is not supported.

Send a /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.
  • The 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"
}
Last update iconLast modified September 2024