• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Simply Connect
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Simply Connect Examples
      • Server-to-Server
        • REST 1.0
        • Server SDKs
          • Java SDK
          • .NET SDK
          • PHP SDK
          • Node.JS SDK
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Marketplaces
      • Self Track
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion: DCC and MCP
          • Multiple Currency Pricing (MCP)
          • Dynamic Currency Conversion (DCC)
            • DCC in Cashier or Payment Page
            • DCC in REST API Workflows
            • DCC in Web SDK Workflows
        • Payout
        • AFT (Account Funding Transactions)
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscriptions (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
          • Challenges and Exemptions
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Addendums
        • Airline
          • External Authorization
        • Local Payment (Installments)
    • Integration
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APMs
        • Testing APIs with Postman
      • Response Handling
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
      • Payment Facilitators (PayFac)
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Merchant-Initiated Transactions (MIT)

    Home    Card Operations    Merchant-Initiated Transactions (MIT)

    On this page:
    • Overview
    • Submit the Initial MIT Payment
    • Submit Subsequent MIT Payments
      • For Payments Originally Initiated by Nuvei
      • For Payments Originally Initiated by an External PSP

    Overview

    A merchant-initiated transaction (MIT) is a payment transaction initiated by a merchant, with the customer’s prior consent. MIT payments are sometimes named subsequent or recurring card payment transactions.

    Card schemes require additional parameters to process MIT payments.

    The MIT flow involves two or more transactions: an initial payment and one or more subsequent payments.

    This topic describes these transactions and the additional parameters to include in these requests:

    • The Initial MIT card payment request, initiated by a customer.
    • Subsequent MIT card payment request/s, initiated by the merchant with the customer’s prior consent, using the customer’s stored credentials.
    Stored Credentials

    Subsequent MIT payment requests are sent by you (with the customer’s prior consent), using the customer’s “cardholder details” (stored credentials).

    • It is recommended to access stored credentials via our Card-on-File/UPO solution (see User Payment Management (Tokenization), which seamlessly handles card schemes’ “Stored Credentials” requirements on your behalf.
    • Only merchants who have the relevant level of PCI compliance are allowed to store cardholder credentials, and payment transactions need to conform to the card schemes’ “Stored Credentials” requirements (see Handling Stored Credentials Yourself).

    Some APM providers offer recurring APM payment services (for example: PayPal, Skrill, and Post finance). After the initial APM payment request, subsequent (recurring) payment requests are sent directly via server-to-server and do not redirect the customer. See the APM subMethod Class topic for details.

    Submit the Initial MIT Payment

    You can use Postman to run a full “Recurring – with 3D-Secure” 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.

    Press tab to open…

    • for REST API
    • for Web SDK

    Perform the relevant steps described in the Server-to-Server topic, and include the following parameters in the Payment step:

    When sending the initial MIT /payment request with its mandatory parameters, include these additional parameters:

    • "isRebilling":"0" to indicate that this is the initial MIT transaction.
    • For a 3D-Secure payment:
      • card.threeD.v2AdditionalParams.rebillFrequency – (format: number of days)
      • card.threeD.v2AdditionalParams.rebillExpiry – (format: YYYYMMDD)

        It is recommended that the rebillExpiry should not be more than 5 years from the initial transaction date.

      • If the /initPayment returned v2supported = true, then include:
        "relatedTransactionId": "<transactionId from the initPayment request>"
      Example Initial MIT /payment Request with 3D 2.0
      { 
         "sessionToken":"<sessionToken from getSessionToken>",
         "merchantId":"<merchantId>",
         "merchantSiteId":"<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":"200",
         "isRebilling":"0",
         "relatedTransactionId": "<transactionId from the initPayment request>",
         "paymentOption":{ 
            "card":{
               "cardNumber":"4000020951595032",
               "cardHolderName":"john smith",
               "expirationMonth":"12",
               "expirationYear":"25",
               "CVV":"217", 
               "threeD":{ 
                  "methodCompletionInd":"Y",
                  "version":"2.1.0",
                  "notificationURL":"<notificationURL>",
                  "merchantURL":"<merchantURL>",
                  "platformType":"02",
                  "v2AdditionalParams":{ 
                     "rebillExpiry":"20200101",
                     "rebillFrequency":"30",
                     "challengeWindowSize":"05"
                   }
               }
            }
         },
         "billingAddress":{ 
            "country":"UK",
            "email":"john.smith@email.com"
         },
         "deviceDetails":{ 
            "ipAddress":"<customer's IP address>"
         },
         "timeStamp":"<YYYYMMDDHHmmss>",
         "checksum":"<calculated checksum>"
      }

    Perform the relevant steps for card or APM payments:

    • For card payments:
      Perform the relevant steps described in the Web SDK – Quick Start topic, and include the following parameters in the Initiate a Session step, in the /openOrder API call to define the initial MIT transaction, as described below.
    • For APM payments:
      Perform the relevant steps described in the APM Payments topic, and include the following parameters in the Initiate a Session step, in the /openOrder API call to define the initial MIT transaction, as described below.

    For both card and APM payments, on the server-side, “define” the initial MIT transaction by sending an /openOrder request with its mandatory parameters, and include these additional parameters:

    • "isRebilling":"0" to indicate that this is the initial MIT transaction.
    • For a 3D-Secure payment:
      • paymentOption.card.threeD.v2AdditionalParams.rebillFrequency – (format: number of days)
      • paymentOption.card.threeD.v2AdditionalParams.rebillExpiry – (format: YYYYMMDD)

        It is recommended that the rebillExpiry should not be more than 5 years from the initial transaction date.

    Example /openOrder Request for Initial MIT with 3D 2.0
    {
      "merchantId": "<your merchantId goes here>",
      "merchantSiteId": "<your merchantSiteId goes here>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "clientRequestId": "<unique request ID in merchant system>",
      "userTokenId": "<unique customer identifier in merchant system>",
      "currency": "USD",
      "amount": "200",
      "isRebilling": "0",
      "paymentOption": {
        "card": {
          "threeD": {
            "v2AdditionalParams": {
              "rebillExpiry": "<Recurring expiry date YYYYMMDD>",
              "rebillFrequency": "<Recurring frequency in days>"
            }
          }
        }
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    for REST API

    Perform the relevant steps described in the Server-to-Server topic, and include the following parameters in the Payment step:

    When sending the initial MIT /payment request with its mandatory parameters, include these additional parameters:

    • "isRebilling":"0" to indicate that this is the initial MIT transaction.
    • For a 3D-Secure payment:
      • card.threeD.v2AdditionalParams.rebillFrequency – (format: number of days)
      • card.threeD.v2AdditionalParams.rebillExpiry – (format: YYYYMMDD)

        It is recommended that the rebillExpiry should not be more than 5 years from the initial transaction date.

      • If the /initPayment returned v2supported = true, then include:
        "relatedTransactionId": "<transactionId from the initPayment request>"
      Example Initial MIT /payment Request with 3D 2.0
      { 
         "sessionToken":"<sessionToken from getSessionToken>",
         "merchantId":"<merchantId>",
         "merchantSiteId":"<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":"200",
         "isRebilling":"0",
         "relatedTransactionId": "<transactionId from the initPayment request>",
         "paymentOption":{ 
            "card":{
               "cardNumber":"4000020951595032",
               "cardHolderName":"john smith",
               "expirationMonth":"12",
               "expirationYear":"25",
               "CVV":"217", 
               "threeD":{ 
                  "methodCompletionInd":"Y",
                  "version":"2.1.0",
                  "notificationURL":"<notificationURL>",
                  "merchantURL":"<merchantURL>",
                  "platformType":"02",
                  "v2AdditionalParams":{ 
                     "rebillExpiry":"20200101",
                     "rebillFrequency":"30",
                     "challengeWindowSize":"05"
                   }
               }
            }
         },
         "billingAddress":{ 
            "country":"UK",
            "email":"john.smith@email.com"
         },
         "deviceDetails":{ 
            "ipAddress":"<customer's IP address>"
         },
         "timeStamp":"<YYYYMMDDHHmmss>",
         "checksum":"<calculated checksum>"
      }

    for Web SDK

    Perform the relevant steps for card or APM payments:

    • For card payments:
      Perform the relevant steps described in the Web SDK – Quick Start topic, and include the following parameters in the Initiate a Session step, in the /openOrder API call to define the initial MIT transaction, as described below.
    • For APM payments:
      Perform the relevant steps described in the APM Payments topic, and include the following parameters in the Initiate a Session step, in the /openOrder API call to define the initial MIT transaction, as described below.

    For both card and APM payments, on the server-side, “define” the initial MIT transaction by sending an /openOrder request with its mandatory parameters, and include these additional parameters:

    • "isRebilling":"0" to indicate that this is the initial MIT transaction.
    • For a 3D-Secure payment:
      • paymentOption.card.threeD.v2AdditionalParams.rebillFrequency – (format: number of days)
      • paymentOption.card.threeD.v2AdditionalParams.rebillExpiry – (format: YYYYMMDD)

        It is recommended that the rebillExpiry should not be more than 5 years from the initial transaction date.

    Example /openOrder Request for Initial MIT with 3D 2.0
    {
      "merchantId": "<your merchantId goes here>",
      "merchantSiteId": "<your merchantSiteId goes here>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "clientRequestId": "<unique request ID in merchant system>",
      "userTokenId": "<unique customer identifier in merchant system>",
      "currency": "USD",
      "amount": "200",
      "isRebilling": "0",
      "paymentOption": {
        "card": {
          "threeD": {
            "v2AdditionalParams": {
              "rebillExpiry": "<Recurring expiry date YYYYMMDD>",
              "rebillFrequency": "<Recurring frequency in days>"
            }
          }
        }
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    Submit Subsequent MIT Payments

    After the initial MIT payment was successfully processed by Nuvei, or by an external PSP, you can begin sending subsequent MIT payment requests.

    Subsequent recurring payments can only be performed from the backend using REST API (not from the frontend via Web SDK).

    Subsequent MIT payment requests are handled differently depending on who sent the original initial MIT payment request:

    • For Payments Originally Initiated by Nuvei
    • For Payments Originally Initiated by an External PSP

    For Payments Originally Initiated by Nuvei

    1. Generate a sessionToken as described in Authentication.
    2. Send subsequent MIT /payment requests with their mandatory parameters, and include these additional parameters:
      • "isRebilling": "1" to indicate that this is a subsequent MIT transaction.
      • "relatedTransactionId": "<transactionId from the original initial customer-initiated transaction>", sent by Nuvei.
        Example Subsequent MIT /payment Request
        {
            "sessionToken": "<sessionToken from getSessionToken>",
            "merchantId": "<merchantId>",
            "merchantSiteId": "<merchantSiteId>",
            "userTokenId":"<unique customer identifier in merchant system>",
            "clientRequestId": "<unique request ID in merchant system>",
            "timeStamp": "<YYYYMMDDHHmmss>",
            "checksum": "<calculated checksum>",
            "currency": "USD",
            "amount": "200",
            "transactionType": "Sale",
            "isRebilling": "1",
            "relatedTransactionId": "<transactionId from the original initial customer-initiated transaction>",
            "paymentOption":{
                "userPaymentOptionId": "<ID of a previously stored payment option>"
            },
            "billingAddress": {
                "country": "US",
                "email": "john.smith@email.com"
            },
            "deviceDetails": {
                "ipAddress": "<customer's IP address>"
            }
        }

    For Payments Originally Initiated by an External PSP

    Prerequisite

    When sending subsequent MIT card payment requests (or recurring card payment transactions), there are cases where the original MIT payment transaction was initiated by an External PSP (acquirer). For example, when a merchant previously used an external PSP, and has now switched to Nuvei as their PSP.

    • If you have access to the following data, then you can include the externalSchemeDetails block when sending subsequent MIT card payment requests (or the recurring card payment transactions):
      • The transactionId (this is the external scheme reference) of the original initial MIT payment transaction, provided by the external PSP.
      • The brand of the card.
    • If you do not have access to this data, then you cannot send the externalSchemeDetails block.
      Instead, follow the steps in the For Payments Originally Initiated by Nuvei section (above).

    Sending subsequent MIT /payment requests:

    1. Generate a sessionToken as described in Authentication.
    2. Send subsequent MIT /payment requests (or recurring card payment transactions) with their mandatory parameters, and include these additional parameters:
      • "isRebilling": "1" to indicate that this is a subsequent MIT transaction.
      • Include the externalSchemeDetails block:
        If you are able to provide the scheme reference (Visa, Mastercard, Amex, Diners, Discover) of the original transaction, then add an externalSchemeDetails block containing these two parameters (required):
        • transactionId – This is the external scheme reference of the original customer-initiated transaction (provided by the external PSP).

          For Mastercard the format should be:
          <3 letters><6 alphanumeric characters><date (4 digits MMDD)>

          For Visa and Amex, the structure for this parameter must be a string of up to 15 numbers.

        • brand – The card brand. Possible values: VISA, MASTERCARD, AMEX, DINERS, DISCOVER.
          • Use the full brand name, all in UPPER CASE.
          • Currently, these are the only brands. Using other brands returns an error.
        Example Subsequent /payment Request with externalSchemeDetails Block
        {
            "sessionToken": "<sessionToken from getSessionToken>",
            "merchantId": "<merchantId>",
            "merchantSiteId": "<merchantSiteId>",
            "userTokenId":"<unique customer identifier in merchant system>",
            "clientRequestId": "<unique request ID in merchant system>",
            "timeStamp": "<YYYYMMDDHHmmss>",
            "checksum": "<calculated checksum>",
            "currency": "USD",
            "amount": "200",
            "transactionType": "Sale",
            "isRebilling": "1",
            "externalSchemeDetails": {
                "transactionId": "<transactionId from the customer-initiated transaction>",
                "brand": "VISA"
            },
            "paymentOption": {
                "card": {
                    "cardNumber": "4000020951595032",
                    "cardHolderName": "john smith",
                    "expirationMonth": "12",
                    "expirationYear": "25",
                    "CVV": "217"
                }
            },
            "billingAddress": {
                "country": "US",
                "email": "john.smith@email.com"
            },
            "deviceDetails": {
                "ipAddress": "<customer's IP address>"
            }
        }
    • Terms of use
    • Privacy Policy
    Nuvei. All rights reserved.