Overview

The Auth-Settle flow allows merchants to perform Authorization and Settlement as separate steps. This topic describes how to implement an Auth-Settle flow using Nuvei REST API 2.0:

1. Authorization – Request that confirms the availability of the payment amount in the customer’s account.
2. Settlement – After receiving authorization from the issuer, the merchant sends one or more settlement requests:

• • A single request that debits from the customer’s account the full authorized amount (full settlement).
  • Multiple requests that add up to the full authorized amount (partial settlements).
    Merchants with a US processingEntityId and that use a TSYS bank as the acquirer can use the Multi-Settle Option.

Authorization

Send a POST /payments request and include one of the following:

• 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 are available to settle the payment. At the end of the time frame, the authorization and the temporary hold expire automatically.
  For example, a merchant that wishes to charge customers only after confirming product availability can first send an authorization request. Later, when the product is ready to be shipped, the merchant can send a settlement request.
• transactionType: “PreAuth” – Similar to an Auth request, except that 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 the merchant charges the customer or the hold expires automatically after 7 to 31 days, depending on the issuer and the industry.
  For example, a car rental company can send a pre-authorization request to temporarily hold $5,000 in the customer’s account. When the car is returned without fines, scratches, or accident damage, the car rental company sends a $400 settlement request that also removes the temporary hold.

Example /payments Request with transactionType: “Auth”

{
  "processingEntityId": "<your processingEntityId>",
  "amount": 10.5,
  "currency": "USD",
  "transactionType": "Auth",
  "paymentOption": {
    "store": "buyerToken",
    "card": {
      "cardNumber": "5101081046006034",
      "cardHolderName": "John Smith",
      "expirationMonth": "10",
      "expirationYear": "2026",
      "cvv": "345"
    }
  },
  "custom": {
    "description": "Some description"
  },
  "deviceDetails": {
    "browser": {
      "acceptHeader": "Y",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
      "javaEnabled": "true",
      "language": "en-US",
      "colorDepth": "24",
      "screenHeight": "1080",
      "screenWidth": "1920",
      "timeZone": "0",
      "javaScriptEnabled": "true"
    }
  },
  "buyerDetails": {
    "buyerId": "<unique customer identifier in your system>",
    "firstName": "John",
    "lastName": "Smith",
    "companyName": "Nuvei Corp",    
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "6175551414",
    "billingAddress": {
      "address": "22 Main Street",
      "zip": "02460",
      "city": "Boston",
      "countryCode": "US",
      "phone": "6175551414",
      "addressMatch": "true"
    },
    "shippingAddress": {
      "sameAsBilling": "true",
      "address": "22 Main Street",
      "zip": "02460",
      "city": "Boston",
      "countryCode": "US",
      "phone": "6175551414"
    }
  }
}

Example /payments Response with result.status: “authorizedOnly”

{
    "paymentId": "375021",
    "transactionId": "2110000000010964387",
    "externalTransactionId": "211010964387",
    "amount": 10.5,
    "currency": "USD",
    "transactionType": "Auth",
    "result": {
        "status": "authorizedOnly"
    },
    "authCode": "961830",    
    "partialApproval": {
        "requestedAmount": 10.5,
        "requestedCurrency": "USD"
    },
    "paymentOption": {
        "card": {
            "cardHolderName": "John Smith",
            "maskedCardNumber": "5****6034",
            "bin": "523233",
            "last4Digits": "6034",
            "expirationMonth": "10",
            "expirationYear": "2026",
            "acquirerId": "99",
            "cardType": "Credit",
            "cardBrand": "MASTERCARD",
            "paymentTokenId": "b058c947-011d-4695-969a-3d6dae9a1d91"
        }
    }
}

If the issuer approves the authorization request, the merchant can continue the flow by:

• Settling the transaction, or by
• Voiding the authorization, which cancels the temporary hold without completing the payment.

Settlement

The merchant can send one or more POST /payments/{payment-id}/settles requests using the paymentId of the original payment transaction. Provide the mandatory parameters for the request. The merchant can:

• Send one request for the full authorized amount (full settlement).
• Send multiple requests that add up to the full authorized amount (partial settlements).

Example /payments/{payment-id}/settles Request

{
    "processingEntityId": "<your processingEntityId>",
    "amount": 5,
    "custom":{
       "description":"test test" 
    }
}

Example /payments/{payment-id}/settles Response

{
  "settleId": "457191",
  "transactionId": "2110000000010751269",
  "amount": 5,
  "currency": "USD",
  "result": {
    "status": "approved"
  },
  "authCode": "377290"
}

Multi-Settle Option

Merchants with a US processingEntityId and that use a TSYS bank as the acquirer can send multiple /payments/{payment-id}/settles requests that add up to the full authorized amount (partial settlements). Include the mandatory parameters and:

totalSettleCount: “<the number (positive integer) of partial settlements into which the settlement is split>”

Include totalSettleCount in the initial /payments/{payment-id}/settles request and in all subsequent /payments/{payment-id}/settles requests. In all requests, the value must be the same.

Example /payments/{payment-id}/settles Request – Multi-Settle Option

{
  "processingEntityId": "<your processingEntityId>",
  "amount": 5,
  "custom": {
    "description": "Some description"
  },
  "totalSettleCounts": 2
}