PayXpert - User documentation
Processing MITs in "external MIT mode"
This page details what to do when initiating a transaction over our API that we did not initially perform.
Version | Date | Comments |
|---|---|---|
1.0 | Sep 29, 2025 | Initial revision |
1.1 | Nov 12, 2025 | Added info on processing scheme field |
Summary
- 1 Introduction
- 1.1 Context
- 2 Implementation
- 2.1 MIT data
- 2.2 API dedicated fields
Introduction
This document describes the way to process “Merchant Initiated Transactions” (MITs) when the initial transaction was not done with PayXpert, while using with the PayXpert low-level transaction processing API (“Gateway API”).
Context
The PayXpert low level transaction processing API provides a full implementation of the MITs.
Depending on the merchant’s implementation, they can either use the PayXpert solution for rebills or manage them on their side.
In addition to this, merchants or integrators can choose to store the card information on their side, if they are PCI-DSS compliant (for example to implement orchestration / routing). In this case, the merchant/integrator will need to integrate specific fields in the Gateway API in order to send PayXpert the necessary information to process the MIT.
Implementation
MIT data
When using the external MIT configuration, the merchant must send all the necessary information to process the transaction. In addition to the standard payment API fields, they need to add new data to properly identify the MIT.
Depending on the integration, the merchant can use the “Sale” or “Authorize” requests (the “Authorize” is mostly for cases where the merchant will send physical goods in a subscription-based program).
The specific data to add are:
context: contains the type of MIT (‘subscriptionIteration’, ‘installmentIteration’ or ‘unscheduledMitIteration’). ‘subscriptionIteration’ corresponds to “subscriptions with a fixed period and amounts” (the schemes definition), while other subscriptions fall into the ‘unscheduledMitIteration” case.
validityDate: for installments, validity date of the whole payment chain
totalAmount: total amount of the payment chain. Mandatory for subscriptions (subscription with a fixed period and amounts) and for installments.
iteration: number of this iteration in the payment chain (the “first payment” counts as ‘1’ if the amount was >0). Mandatory for subscriptions and for installments.
totalIterations: total number of payments in the chain, if known. Mandatory for subscriptions and for installments.
paymentMeanType: type of card information entry. For this case, ‘cardNumber’.
originalSchemeTransactionId: the “Scheme Transaction Id” received in the response for the first payment of the chain. You should add a character at the beginning to enrich it with the scheme sending this ID
Carte Bancaire → ‘1’
MasterCard → ‘2’
Visa → ‘3’
If the original transaction was processed with PayXpert, the ‘schemeTransactionID’ that you received in the API response will already contain the first digit.
API dedicated fields
To have the complete list of fields to process a transaction, please refer to the official API documentation at: https://developers.payxpert.com/gateway/..
The ‘processingScheme’ field is mandatory in this use case.
Specific fields are used in the transaction processing low-level API to provide the MIT-specific data in the case of merchants managing their own tokenization, the table below describes them.
External MIT API Parameters:
Field name | Description | Requirement |
payment.context | ‘subscriptionIteration’, ‘installmentIteration’ or ‘unscheduledMitIteration’ | Mandatory |
payment.recurrence.validityDate | Validity date of the whole payment chain. Format = YYYYMMDD. | Mandatory for subscriptions and installments |
payment.recurrence.totalAmount | Total amount of the payment chain. Format = int(12) | Mandatory for subscriptions and installments |
payment.recurrence.iteration | Number of this iteration in the payment chain Format = int(2) | Mandatory for subscriptions and installments |
payment.recurrence.totalIterations | Total number of payments in this payment chain. Format = int(2) | Mandatory for subscriptions and installments |
payment.paymentMeanType | ‘cardNumber’ | Optional |
payment.originalSchemeTransactionId | Concatenation of the scheme + the scheme transaction Id of the first payment in the chain. Format = String(50) | Mandatory |
Additional SCA info fields that can help: | ||
initialSca.dsTransID | Universally unique transaction identifier assigned by the 3DS Server identifying the initial SCA authentication for the transaction. | Optional |
initialSca.acsTransID | The card issuer’s Access Control Server Transaction ID from the initial challenge or (frictionless flow) for the transaction. | Optional |
initialSca.authMode | The authentication mode used during the original transaction's SCA flow. | Optional |
initialSca.authValue | CRes (challenge result value) returned by the ACS during the original 3DS transaction. | Optional |
initialSca.authMerchantName | The name of the merchant associated with the original SCA authentication. | Optional |
initialSca.authDate | ISO 8601 timestamp of the SCA authentication regarding the initial transaction. | Optional |
initialSca.authAmount | The transaction amount that was authenticated in the initial SCA flow. | Optional |
Here is an example of how those new fields should be sent in the request :
{
...
"payment": {
"context": "subscriptionIteration",
"recurrence": {
"validityDate": "20251231",
"totalAmount": 1234567,
"iteration": 3,
"totalIterations": 10
},
"paymentMeanType": "cardNumber",
"originalSchemeTransactionId": "3485202383668035"
}
...
}