Merchant Initiated Transactions (MITs) are typical of industries whose business models involve payments occurring in a different time from the moment of purchase.
In these scenarios, the buyer allows the merchant to proceed with future payments by accepting the terms and conditions of the agreement between the parties.
Examples of such industries are: subscription based services, utilities, pay-per-use and installments.
When dealing with recurring payments, two types of transactions must be known and performed correctly:
Customer Initiated Transactions (CITs)
The first transactions in each chain of recurring payments. They require Strong Customer Authentication (SCA), which allows to verify the authenticity of the payer and to have reference for subsequent transactions, without the payer being present.
Merchant Initiated Transaction (MITs)
Transactions initiated by the merchant without the buyer being present, performed according to terms and conditions accepted in a previous agreement between the parties.
MITs are out of scope for PSD2 and do not require an authentication.
Fabrick Payment Orchestra supports two types of MIT:
Recurring Transactions: Transactions whose amount and frequency are constant.
Unscheduled Transactions: Transactions whose amount and frequency are variable.
All MIT types share the following requirements:
An agreement between the the merchant and the buyer allowing the former to initiate transactions on the account of the latter.
MITs must refer to the first transaction performed (CIT), marked as the first in the series.
The first transaction (CIT), to which subsequent MITs will refer, must be authenticated by SCA.
In order to process transactions with an off-session buyer (MITs), the payment credentials employed to complete the transaction are usually tokenized during the initial transaction (CIT).
Recurring transactions are indicated for use cases where the amount and frequency of payments are known in advance.
For example, the subscription to digital services: in these cases, the payment process includes an initial transaction requiring two-factor authentication (SCA), which we will refer to as First (CIT), and a series of periodic transactions, called Next (MITs). The latters are charged to the customer upon subscription to the service (i.e. the agreement between the parties).
In order to process this type of transactions correctly, the following mandatory fields must be properly filled in:
First Recurring Payment (CIT):
type = 01F (please verify the "type" category through the examples at the end of the page).
authenticationAmount: maximum expected payment amount according to the agreement between the parties.
expiry: end date of the agreement.
frequency: minimum number of days between payments.
Upon completing the payment, Fabrick will provide an identifier for the payment series to be employed for processing subsequent MITs.
Next Recurring Payment (MIT):
type = 01N
previousTransDetails: this object contains the information needed in order to link the MITs to their respective SCA authenticated first transactions. Any of the following fields can be used:
bankTransactionID: this is the field we recommend to specify. It is the first recurring payment's identifier. For integration via SOAP API, please use the parameter bankTransactionID; for integration via REST API, please use the transaction’s paymentID.
XID: unique ID assigned by the Directory Server.
Previous 3DS2 authentication data: in this case, all of the following fields must be properly filled in: authData, authMethod, authTimestamp, acsID.
Unscheduled Transactions have variable payment amount and frequency. This type of transactions is ideal for business models involving consumption-based pricing, in case of no-show fees and penalties application (for example, in the case of damaged rented goods).
The integration procedure for Unscheduled Transactions follows the general guidelines for MITs, while presenting fewer limitations than recurring payments:
1. First Unscheduled Transaction (CIT):
type = 03F
authenticationAmount: maximum expected payment amount according to the agreement between the parties.
Upon completing the payment, Fabrick will provide an identifier for the payment series to be employed for processing Next MITs.
2. Next Unscheduled Transaction (MIT):
type = 03N
previousTransDetails: this object contains the information needed in order to link the MITs to their respective SCA authenticated first transactions. Any of the following fields can be used:
bankTransactionID: this is the field we recommend to specify. It is the first recurring payment's identifier. For integration via SOAP API, please use the parameter bankTransactionID; for integration via REST API, please use the transaction’s paymentID.
XID: unique ID assigned by the Directory Server.
Previous 3DS2 authentication data: in this case, all of the following fields must be properly filled in: authData, authMethod, authTimestamp, acsID.
Cancelling the initial payment, whether 01F or 03F, incurs in the risk of generating errors on subsequent payments. Therefore, in order to avoid the risk of performance deterioration, it must be ensured to correctly process the CITs and disable cancellation processes of authorizations, for example, in case of free trial periods.
It is not uncommon for a service to include a free trial period or a final balance payment to be processed later than the buyer in-session's payment.
For managing this type of transactions, the merchant may set the "amount" field in the initial transaction to "0". On the other hand, the "authenticationAmount" field must be set to the expected amount for subsequent charges. This will generate a new MIT payment chain, providing an ideal shopping experience for the payer, who will not be charged any amount during the trial period.
Below there is an example for SOAP API:
1 {
22 "shopLogin": "GESPAY00001",
33 "amount": "0",
44 "currency": "EUR",
55 "shopTransactionID": "OrderID_01F_001",
66 "transDetails": {
77 "type": "01F",
88 "authenticationAmount": "10",
99 "recurringTransaction":{
1010 "expiry": "20301225",
1111 "frequency": "14"
1212 }
1313 }
1414}
Until October 31st 2022, transactions in progress and prior to the adoption of the 3DS2 protocols may be processed without a first authenticated transaction (CIT) or its identifier.
These MITs are referred to as Grandfathered Transactions and can be processed by using the following tags:
type: It is necessary to define the MIT type. Possible values are the following:
01N for Recurring Transactions.
03N for Unscheduled MITs.
bankTransactionID: -100
Unlike transactions originated within the PSD2 regulatory context, Grandfathered Transactions do not require the filing of any identifier referring to the first transaction of the series (CIT), and thus a proper authentication of the buyer.
Each MIT is to be processed with a bankTransactionID: -100 reference until the agreement between the parties is renewed involving a new authentication of the buyer. When this happens, a new chain of subsequent payments will start, according to the requirements for the corresponding MITs type.
With effect from October 31st 2022, Payment Schemes will dispose of Grandfathered Transactions: in order to avoid conversion rate reductions, please make sure that MIT payments are processed correctly according to the guidelines described above.
If a transaction is processed without complying with the guidelines regarding authentication and possible exclusions (such as MITs), it may be rejected with error type 8026 "Soft decline - Cardholder authentication required".
In this case, the buyer will have to be engaged and asked to complete a First transaction, authenticating the payment, so that a new chain of subsequent transactions can be started according to the requirements.
Here are some examples:
Encrypt - 01F
1 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecom="https://ecomm.sella.it/">
2 <soapenv:Header/>
3 <soapenv:Body>
4 <ecom:Encrypt>
5 <ecom:shopLogin>GESPAY00001</ecom:shopLogin>
6 <ecom:uicCode>242</ecom:uicCode>
7 <ecom:amount>0</ecom:amount>
8 <ecom:shopTransactionId>OrderID_01F_001</ecom:shopTransactionId>
9 <ecom:requestToken>MASKEDPAN</ecom:requestToken>
10 <ecom:transDetails>
11 <ecom:type>01F</ecom:type>
12 <ecom:authenticationAmount>10</ecom:authenticationAmount>
13 <ecom:recurringTransaction>
14 <ecom:expiry>20301225</ecom:expiry>
15 <ecom:frequency>14</ecom:frequency>
16 </ecom:recurringTransaction>
17 </ecom:transDetails>
18 <ecom:apikey></ecom:apikey>
19 </ecom:Encrypt>
20 </soapenv:Body>
21</soapenv:Envelope>
callPagamS2S - 01N
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecom="https://ecomms2s.sella.it/">
2 <soapenv:Header/>
3 <soapenv:Body>
4 <ecom:callPagamS2S>
5 <ecom:shopLogin>GESPAY00001</ecom:shopLogin>
6 <ecom:uicCode>242</ecom:uicCode>
7 <ecom:amount>10</ecom:amount>
8 <ecom:shopTransactionId>OrderID_01N_001</ecom:shopTransactionId>
9 <ecom:tokenValue><!-- Token received in the 01F :--></ecom:tokenValue>
10 <ecom:transDetails>
11 <ecom:type>01N</ecom:type>
12 <ecom:previousTransDetails>
13 <ecom:bankTransactionID><!-- bankTransactionID of the 01F :--></ecom:bankTransactionID>
14 </ecom:previousTransDetails>
15 </ecom:transDetails>
16 <ecom:apikey></ecom:apikey>
17 </ecom:callPagamS2S>
18 </soapenv:Body>
19</soapenv:Envelope>
Encrypt - 03F
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecom="https://ecomm.sella.it/">
2 <soapenv:Header/>
3 <soapenv:Body>
4 <ecom:Encrypt>
5 <ecom:shopLogin>GESPAY00001</ecom:shopLogin>
6 <ecom:uicCode>242</ecom:uicCode>
7 <ecom:amount>0</ecom:amount>
8 <ecom:shopTransactionId>OrderID_03F_001</ecom:shopTransactionId>
9 <ecom:requestToken>MASKEDPAN</ecom:requestToken>
10 <ecom:transDetails>
11 <ecom:type>03F</ecom:type>
12 <ecom:authenticationAmount>10</ecom:authenticationAmount>
13 </ecom:transDetails>
14 <ecom:apikey></ecom:apikey>
15 </ecom:Encrypt>
16 </soapenv:Body>
17</soapenv:Envelope>
callPagamS2S - 03N
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecom="https://ecomms2s.sella.it/">
2 <soapenv:Header/>
3 <soapenv:Body>
4 <ecom:callPagamS2S>
5 <ecom:shopLogin>GESPAY00001</ecom:shopLogin>
6 <ecom:uicCode>242</ecom:uicCode>
7 <ecom:amount>10</ecom:amount>
8 <ecom:shopTransactionId>OrderID_03N_001</ecom:shopTransactionId>
9 <ecom:tokenValue><!-- Token received in the 03F :--></ecom:tokenValue>
10 <ecom:transDetails>
11 <ecom:type>03N</ecom:type>
12 <ecom:previousTransDetails>
13 <ecom:bankTransactionID><!-- bankTransactionID of the 03F :--></ecom:bankTransactionID>
14 </ecom:previousTransDetails>
15 </ecom:transDetails>
16 <ecom:apikey></ecom:apikey>
17 </ecom:callPagamS2S>
18 </soapenv:Body>
19</soapenv:Envelope>
Type 01F and 03F transactions must not be cancelled.
The amount field in transactions of type 01F and 03F may be set as follows:
amount=0 when no charge is to be applied to the buyer's card (for example, during the free trial period).
In this case, no additional action by the merchant is required.
amount>0 when the transaction is to be charged on the buyer and the order will be associated with a collection.
In this case, the transaction may be captured normally.
payment/create - 01F
1 {
2 "shopLogin": "GESPAY00001",
3 "amount": "0",
4 "currency": "EUR",
5 "shopTransactionID": "OrderID_01F_001",
6 "transDetails": {
7 "type": "01F",
8 "authenticationAmount": "10",
9 "recurringTransaction":{
10 "expiry": "20301225",
11 "frequency": "14"
12 }
13 }
14}
payment/submit - 01F
1 {
2 "shopLogin": "GESPAY00001",
3 "paymentType": "CreditCard",
4 "paymentTypeDetails": {
5 "creditcard": {
6 "number": "4012000000003101",
7 "token": "",
8 "expMonth": "05",
9 "expYear": "27",
10 "CVV": "390",
11 "requestToken": "MASKEDPAN",
12 "DCC": ""
13 }
14 }
15}
payment/create - 01N
1{
2 "shopLogin": "GESPAY00001",
3 "amount": "10",
4 "currency": "EUR",
5 "shopTransactionID": "OrderID_01N_001",
6 "transDetails": {
7 "type": "01N",
8 "previousTransDetails":{
9 "paymentID": ""/*paymentID of the 01F */
10 }
11 }
12}
payment/submit - 01N
1{
2 "shopLogin": "GESPAY00001",
3 "paymentType": "CreditCard",
4 "paymentTypeDetails": {
5 "creditcard": {
6 "number": "",
7 "token": "", /* Token received in the 01F */
8 "expMonth": "",
9 "expYear": "",
10 "CVV": "",
11 "requestToken": "",
12 "DCC": ""
13 }
14 }
15}
payment/create - 03F
1{
2 "shopLogin": "GESPAY00001",
3 "amount": "0",
4 "currency": "EUR",
5 "shopTransactionID": "OrderID_03F_001",
6 "transDetails": {
7 "type": "03F",
8 "authenticationAmount": "10"
9 }
10}
payment/submit - 03F
1{
2 "shopLogin": "GESPAY00001",
3 "paymentType": "CreditCard",
4 "paymentTypeDetails": {
5 "creditcard": {
6 "number": "4012000000003101",
7 "token": "",
8 "expMonth": "05",
9 "expYear": "27",
10 "CVV": "390",
11 "requestToken": "MASKEDPAN",
12 "DCC": ""
13 }
14 }
15}
payment/create - 03N
1{
2 "shopLogin": "GESPAY00001",
3 "amount": "10",
4 "currency": "EUR",
5 "shopTransactionID": "OrderID_03N_001",
6 "transDetails": {
7 "type": "03N",
8 "previousTransDetails":{
9 "paymentID": ""/*paymentID of the 03F */
10 }
11 }
12}
payment/submit - 03N
1 {
2 "shopLogin": "GESPAY00001",
3 "paymentType": "CreditCard",
4 "paymentTypeDetails": {
5 "creditcard": {
6 "number": "",
7 "token": "", /* Token received in the 03F */
8 "expMonth": "",
9 "expYear": "",
10 "CVV": "",
11 "requestToken": "",
12 "DCC": ""
13 }
14 }
15}
Type 01F and 03F transactions must not be cancelled.
The amount field in transactions of type 01F and 03F may be set as follows:
amount=0 when no charge is to be applied to the buyer's card (for example, during the free trial period).
In this case, no additional action by the merchant is required.
amount>0 when the transaction is to be charged on the buyer and the order will be associated with a collection.
In this case, the transaction may be captured normally.