To successfully process Card on File (COF) transactions, it is important to send the right standingInstruction.* parameters. Below you can find information about the mandatory, conditional and optional fields in the request and response messages. The parameters apply across all COF use cases: One-click, MIT and MIT Industry Practice agreements, as well as importing MIT agreements.

Most parameters are conditional, which means that they depend on the use case, the card brand or the integration. Please check the conditions in the tables below, and the parameters per use case overview.

For step-by-step guidance and sample requests, please refer to the Card on File guide. For more information about all other request and response fields, please refer to our API reference guide.

Request parameters

Agreement data

Field name	Mandatory/Optional	Format, Length
standingInstruction.type	Conditional	Values accepted: • UNSCHEDULED • INSTALLMENT • RECURRING Refer to the table below
standingInstruction.recurringType	Conditional Required for all Mastercard CIT and MIT, and for Visa Recurring transactions executed with cards issued in India	Values accepted: • STANDING_ORDER • SUBSCRIPTION Refer to the table below
standingInstruction.mode	Conditional	Values accepted: • INITIAL • REPEATED
standingInstruction.source	Conditional	Values accepted: • CIT • MIT
standingInstruction.industryPractice	Conditional	Values accepted: • INCREMENTAL_AUTH • RESUBMISSION • REAUTHORIZATION • DELAYED_CHARGES • NO_SHOW Refer to the table below

Scheme reference data

Field name	Mandatory/Optional	Format, Length
standingInstruction.initialTransactionId	Conditional Required in MIT transactions when the card isn't tokenized by our platform	Format: AN or N No specific format, depends on the acquirer
standingInstruction.agreementId	Optional	Length: Variable, maximum 35 characters Format: AN

3D Secure data for recurring and installment payments

Field name	Mandatory/Optional	Format, Length
standingInstruction.expiry	Conditional Mandatory when processing 3D Secure on recurring or installment transactions	Format: yyyy-mm-dd
standingInstruction.frequency	Conditional Mandatory when processing 3D Secure on recurring or installment transactions	Length: 4 characters Format: Numeric
standingInstruction.numberOfInstallments	Conditional Mandatory when processing 3D Secure on installment transactions	Length: Variable, maximum 3 characters Format: Numeric

Parameters per use case

The table below shows which standingInstruction.* values are used in each request of the three COF use cases.

Use case	Request	Parameters
One-click agreement	Store the card (CIT, initial)	type=UNSCHEDULED mode=INITIAL source=CIT createRegistration=true
One-click agreement	One-click payment (CIT, repeated)	type=UNSCHEDULED mode=REPEATED source=CIT
MIT agreement	Create the agreement (CIT, initial)	type=RECURRING, INSTALLMENT or UNSCHEDULED recurringType (when type is RECURRING) mode=INITIAL source=CIT expiry, frequency, numberOfInstallments (3D Secure) createRegistration=true
MIT agreement	Merchant-initiated payment (MIT, repeated)	type, recurringType (same as initial) mode=REPEATED source=MIT initialTransactionId (if the card isn't tokenized by our platform) agreementId (Mastercard)
MIT Industry Practice agreement	Create the agreement (CIT, initial)	type=UNSCHEDULED mode=INITIAL source=CIT createRegistration=true
MIT Industry Practice agreement	Industry practice payment (MIT, repeated)	type=UNSCHEDULED mode=REPEATED source=MIT industryPractice (for example NO_SHOW) initialTransactionId

Transaction category

Send the field standingInstruction.type with one of the following values:

Value	Description
RECURRING	Transactions processed on a regular fixed interval for a pre-agreed or advised amount, where applicable. Recurring transactions don't have a fixed duration and continue to be processed until the cardholder cancels the agreement.
INSTALLMENT	Transactions processed on a regular fixed interval for a pre-agreed amount for a single purchase of goods or services. Unlike recurring transactions, installment payments have a fixed duration and shouldn't continue to be processed after the end of the agreed installment period.
UNSCHEDULED	Similar to a recurring transaction, but it does not happen at pre-agreed intervals. The classic example is a transaction triggered by an event such as an amount threshold, to ensure that a pay-as-you-go account always has a minimum available reserve.

Recurring type

Send the field standingInstruction.recurringType with one of the following values to indicate the type of a recurring MIT agreement. The value has to be provided when the consumer agrees to store the credential-on-file and initiates the first transaction in a series.

Value	Description
STANDING_ORDER	The series is intended to be for a variable amount and a fixed frequency. Example: The initial transaction to store the credential-on-file for a monthly utility payment.
SUBSCRIPTION	The series is intended to be for a fixed amount and a fixed frequency. Example: The initial transaction to store the credential-on-file for a monthly newspaper subscription.

Mode and source

Field name	Value	Description
standingInstruction.mode	INITIAL	The payment is the first of a series of payments. This first payment must contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.
standingInstruction.mode	REPEATED	The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters, as the shopper is not present anymore.
standingInstruction.source	CIT	Cardholder initiated transaction.
standingInstruction.source	MIT	Merchant initiated transaction.

Industry practice

The MIT types defined under this category are performed to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with one single transaction. Send the field standingInstruction.industryPractice with one of the following values:

Value	Description
INCREMENTAL_AUTH	Used to increase the total amount authorized. Incremental authorizations do not replace the original authorization, they are additional to previously authorized amounts. The sum of all linked estimated and incremental authorizations represents the total amount on hold in the cardholder's account for a given transaction.
RESUBMISSION	When a merchant attempts to authorize a transaction after the service has been used but the issuer declines it for insufficient funds, they may attempt to re-authorize to recover the debt. These authorization requests are considered resubmission authorizations and must carry the new "re submission" indicator.
REAUTHORIZATION	Occurs when a merchant has a need to submit an authorization request after the cardholder has left the point of interaction and there is no possibility of re-authenticating the card or the cardholder. A merchant may need to do this if they intend to split the shipment into multiple deliveries and will only authorize as goods come into stock. The subsequent authorization requests carry the new "re-authorization" marker and the scheme reference data from the initial interaction.
DELAYED_CHARGES NO_SHOW	Such transactions occur largely in the rental and hospitality sectors. These transactions also carry the scheme reference data provided in the initial authorization at the start of the rental or stay agreement, as well as in the settlement record.

Scheme reference IDs

The fields below link merchant-initiated payments back to the original agreement.

Field name Description

standingInstruction.initialTransactionId

Field name	Description
standingInstruction.initialTransactionId	The reference ID generated by the scheme for the transaction (in some integrations, the processor provides its own internal ID instead of the scheme value). It is returned by the processor or acquirer as part of the CIT transaction response. The ID is received in one of the following response fields, depending on the integration (refer to the respective Connector Integration sheet): standingInstruction.initialTransactionId resultDetails.CardholderInitiatedTransactionID The field is required in MIT transactions when the card isn't tokenized by our platform.
standingInstruction.agreementId	Used for Mastercard transactions to transmit the Economically Related Transaction ID (TLID), which identifies and links transactions associated with the same standing instruction agreement (for example, merchant-initiated transactions and refunds). During a transitional period, both `standingInstruction.initialTransactionId` and `standingInstruction.agreementId` will be returned by Mastercard and are expected to be provided in MIT requests. After the transition period, only `standingInstruction.agreementId` will be returned in responses and expected in requests.

The reference ID generated by the scheme for the transaction (in some integrations, the processor provides its own internal ID instead of the scheme value). It is returned by the processor or acquirer as part of the CIT transaction response.

The ID is received in one of the following response fields, depending on the integration (refer to the respective Connector Integration sheet):

standingInstruction.initialTransactionId
resultDetails.CardholderInitiatedTransactionID

The field is required in MIT transactions when the card isn't tokenized by our platform.

standingInstruction.agreementId

Used for Mastercard transactions to transmit the Economically Related Transaction ID (TLID), which identifies and links transactions associated with the same standing instruction agreement (for example, merchant-initiated transactions and refunds).

During a transitional period, both standingInstruction.initialTransactionId and standingInstruction.agreementId will be returned by Mastercard and are expected to be provided in MIT requests. After the transition period, only standingInstruction.agreementId will be returned in responses and expected in requests.

Default values in the 3D Secure authentication request

If the parameters below are not sent, the platform applies the following defaults within the authentication request.

Field name	Mastercard	Other brands
standingInstruction.expiry	Date after which no further authorizations will be performed. Default value: 9999-12-31	The authentication request is sent with indicator "payment" (not "recurring").
standingInstruction.frequency	Minimum number of days between authorizations. Default value: 0001	The authentication request is sent with indicator "payment" (not "recurring").
standingInstruction.numberOfInstallments	Maximum number of authorizations permitted for installment payments. Required if the merchant and cardholder have agreed to installment payments and EMV 3D authentication is configured, i.e. if standingInstruction.type=INSTALLMENT. Omitted if not an installment payment authentication.

Response parameters

The scheme reference of the agreement is returned in the response of the initial CIT transaction. Store it in your systems, as it is required for subsequent MIT requests when the card isn't tokenized by our platform.

Value	Description
standingInstruction.initialTransactionId	Reference ID generated by the scheme for the initial transaction, depending on the integration.
resultDetails.CardholderInitiatedTransactionID	Reference ID of the initial cardholder-initiated transaction, returned instead of the field above in some integrations.
standingInstruction.agreementId	Mastercard only. The Economically Related Transaction ID (TLID) linking all transactions of the agreement.