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, also known as a customer-initiated transaction (CIT).
- The 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).
Submit the Initial MIT Payment
Press tab to open…
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.- For a 3D-Secure payment:
card.threeD.v2AdditionalParams.rebillFrequency
– (format: number of days)card.threeD.v2AdditionalParams.rebillExpiry
– (format: YYYYMMDD)- If the
/initPayment
returnedv2supported
= 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":"GB", "email":"[email protected]" }, "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, 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, as described below.
For both card and APM payments, on the server-side, “define” the initial MIT by sending an /openOrder request with its mandatory parameters, and include these additional parameters:
isRebilling
: “0” to indicate that this is the initial MIT.- For a 3D-Secure payment:
paymentOption.card.threeD.v2AdditionalParams.rebillFrequency
– (format: number of days)paymentOption.card.threeD.v2AdditionalParams.rebillExpiry
– (format: YYYYMMDD)
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>" }
- 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.- For a 3D-Secure payment:
card.threeD.v2AdditionalParams.rebillFrequency
– (format: number of days)card.threeD.v2AdditionalParams.rebillExpiry
– (format: YYYYMMDD)- If the
/initPayment
returnedv2supported
= 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":"GB", "email":"[email protected]" }, "deviceDetails":{ "ipAddress":"<customer's IP address>" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
- 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, 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, as described below.
For both card and APM payments, on the server-side, “define” the initial MIT by sending an /openOrder request with its mandatory parameters, and include these additional parameters:
isRebilling
: “0” to indicate that this is the initial MIT.- For a 3D-Secure payment:
paymentOption.card.threeD.v2AdditionalParams.rebillFrequency
– (format: number of days)paymentOption.card.threeD.v2AdditionalParams.rebillExpiry
– (format: YYYYMMDD)
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 card payments:
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 MIT payment requests are handled differently depending on who sent the original initial MIT payment request:
For Payments Originally Initiated by Nuvei
- Generate a
sessionToken
as described in . - Send subsequent MIT
/payment
requests with their mandatory parameters, and include these additional parameters:isRebilling
: “1” to indicate that this is a subsequent MIT.relatedTransactionId
: “<transactionId
from the original initial CIT> (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 CIT>", "paymentOption":{ "userPaymentOptionId": "<ID of a previously stored payment option>" }, "billingAddress": { "country": "US", "email": "[email protected]" }, "deviceDetails": { "ipAddress": "<customer's IP address>" } }
For Payments Originally Initiated by an External PSP
Sending subsequent MIT /payment
requests:
- Generate a
sessionToken
as described in . - 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.- Include the
externalSchemeDetails
block:
If you are able to provide the scheme reference (Visa, Mastercard, Amex, Diners, Discover) of the original transaction, then add anexternalSchemeDetails
block containing these two parameters (required):transactionId
– This is the external scheme reference of the original CIT (provided by the external PSP).
brand
– The card brand. Possible values: VISA, MASTERCARD, AMEX, DINERS, DISCOVER.
Example Subsequent
/payment
Request withexternalSchemeDetails
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 CIT>", "brand": "VISA" }, "paymentOption": { "card": { "cardNumber": "4000020951595032", "cardHolderName": "john smith", "expirationMonth": "12", "expirationYear": "25", "CVV": "217" } }, "billingAddress": { "country": "US", "email": "[email protected]" }, "deviceDetails": { "ipAddress": "<customer's IP address>" } }