# Credential on File Transactions source: https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md The following sections describe how to submit cardholder-initiated and merchant-initiated transactions (CIT and MIT) to the Mastercard Gateway to comply with card scheme standards for processing these transactions: * Cardholder-initiated payments: * Merchant-initiated payments: For general information about the preceding scenarios, see [Cardholder and Merchant-initiated Payments](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/cit-mit/index.md). For full examples of the requests for all scenarios, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). Tip: Integrate with API version 100 for full compatibility. CIT and MIT are supported from API version 74 or later. Whenever you submit multiple payments in a series, the first transaction must be a CIT which provides the cardholder's approval for the entire series. The subsequent transactions are usually MITs. In all requests, you can use the `transaction.source` field to identify whether a transaction is cardholder or merchant initiated, and the `sourceOfFunds.provided.card.storedOnFile` field to indicate whether the payment details are to be stored, have been previously stored, or you intend to store them. For more information, see the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md#faqs). Warning: * To be able to submit any MITs, your payment service provider must have MERCHANT enabled as an allowable transaction source on your merchant acquirer link. * If you want to store the payer's payment details in the gateway and use a token to refer to the stored details, your PSP must configure a merchant profile for [gateway tokenization](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/gw-tokenization/index.md). ## CITs in general {#cits-in-general} A CIT transaction can be a one-off payment where you typically do not store the payment details provided by the payer. However, the payer can consent for you to store their payment details for future use (usually as part of a customer registration or account creation process) so that you can offer subsequent cardholder-initiated transactions using the stored payment details. In the initial transaction request with a new customer, you need to provide the following fields: * `sourceOfFunds.type` = CARD or SCHEME_TOKEN Value depends on whether you are providing the raw card details or a token (having already tokenized the card details). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source` = INTERNET Value indicates to the gateway that the transaction is cardholder initiated. You can set the value to INTERNET, MOTO, MAIL_ORDER, TELEPHONE_ORDER, VOICE_RESPONSE, or CALL_CENTER. Warning: In all examples on this site, the INTERNET value is used. However, you should indicate the channel through which you received the payment. * `sourceOfFunds.provided.card.storedOnFile` = TO_BE_STORED Value indicates that the payer agrees for you to store their payment details for future use. In any subsequent payments initiated by the payer (not by you) and where the payer's stored payment details are used, you must provide the following fields in the request: * `sourceOfFunds.type` = CARD or SCHEME_TOKEN Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source` = INTERNET * `sourceOfFunds.provided.card.storedOnFile` = STORED For more details on how to indicate to the gateway how and whether the payment details are to be stored, see the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md#faqs). ## CITs with EMV 3-D Secure {#cits-with-emv-3-d-secure} The CITs can be authenticated with EMV 3-D Secure to identify the cardholder and prevent fraud. You can use the EMV 3-D Secure in: * One-off CITs * CITs which form the first step in a series of payments, where the subsequent ones are MITs * Scenarios where you want to authenticate the cardholder when adding their card to the customer account for future use The following table describes some detailed use cases related to [EMV 3-D Secure authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md). For more information on both EMV 3-D Secure authentication in the gateway and using external authorization in payment transactions, see [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md). | Use Case | Integration Steps | |-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Agreement with the payer for recurring payments, including an initial charge in the CIT | **Step 1:** Perform Authentication as described in the [Authentication guidelines](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) and specify the amount required for the initial payment. **Step 2:** Create the CIT request with the details defined in the [Cardholder-initiated Payments](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md#cits-in-general) section and add one of the following: * `authentication.transactionId` using the transaction ID from the gateway authentication request * EMV 3-D Secure data from a third-party (if you used external authorization) | | Agreement with the payer for recurring payments, including no initial charge in the CIT | This use case covers recurring payment series where no payment is due at the moment the payer signs up for the service. While performing authentication as described in the [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md) topic, use the additional fields specified in the following steps to integrate EMV 3-D Secure for recurring payments. **Step 1:** Perform the INITIATE AUTHENTICATION operation and set `authentication.purpose` to `ADD_CARD` or `MAINTAIN_CARD`. **Step 2:** Perform the AUTHENTICATE PAYER operation with the following fields: * `Amount = 0` * `agreement.type = Recurring` * `agreement.expiryDate` * `agreement.minimumDaysBetweenPayments` **Step 3:** As the CIT request, perform the VERIFY operation request and add one of the following: * `authentication.transactionId` using the transaction ID from the gateway authentication result and the same `agreement.*` fields as in the INITIATE AUTHENTICATION request * EMV 3-D Secure data from a third-party (if you used external authorization) Warning: If you are using the [Hosted Session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/index.md) integration, complete steps 1 and 2 within the session and then use the session ID (from the session created for steps 1 and 2) when sending the request from your server in step 3. | | Add Card without Payment Agreement | This use case covers a scenario where the payer wants to add their card details while creating their profile or customer account with you without any immediate payment. The payer can use the stored card in the future for one-off payments or to establish a payment agreement for a series of payments. **Step 1:** Perform the INITIATE AUTHENTICATION operation and set `authentication.purpose` to `ADD_CARD` or `MAINTAIN_CARD`. **Step 2:** Perform the AUTHENTICATE PAYER operation and set `amount` to `0`. **Step 3:** As the CIT request, perform the VERIFY operation request and add one of the following: * `authentication.transactionID` using the transaction ID from the gateway authentication result and the same `agreement.*` fields as in the INITIATE AUTHENTICATION request * EMV 3-D Secure data from a third-party (if you used external authorization) Warning: If you are using the [Hosted Session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/index.md) integration, complete steps 1 and 2 within the session and then use the session ID (from the session created for steps 1 and 2) when sending the request from your server in step 3. | The following fields are needed in the [AUTHENTICATE PAYER](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) operation to have a successful recurring transaction: When using API v61 or later: * `agreement.id` * `agreement.type=RECURRING` * `agreement.numberOfPayments` * `agreement.amountVariability` * `agreement.expiryDate` * `agreement.paymentFrequency` * `agreement.minimumDaysBetweenPayments` When using API v57 - v60: * `agreement.id` * `agreement.type=RECURRING` * `agreement.expiryDate` * `agreement.recurring.daysBetweenPayments` ## Merchant-initiated recurring payments {#merchant-initiated-recurring-payments} You can submit recurring payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer that authorizes you to initiate subsequent recurring payments without the payer's active participation. In the initial CIT request, you need to provide the following fields to set up the agreement: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether you are providing the raw card details or a token (having already tokenized the card details). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source`=INTERNET, and Value indicates to the gateway that the transaction is cardholder initiated. * `sourceOfFunds.provided.card.storedOnFile`=TO_BE_STORED Value indicates that the payer agrees for you to store their payment details for future use. * `agreement.id` Unique value generated by you to identify a payment agreement with the payer. * `agreement.type`=RECURRING Standing instruction agreement that you have established with the payer. Warning: The following fields are needed in processing a successful recurring transaction: * When using API v61 and onwards: * `agreement.amountVariability` * `agreement.expiryDate` * `agreement.minimumDaysBetweenPayments` * When using API v57 - v60: * `agreement.expiryDate` * `agreement.recurring.daysBetweenPayments` In any subsequent MIT requests, you must provide the following fields: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source`=**MERCHANT** Value indicates to the gateway that the transaction is merchant initiated. * `sourceOfFunds.provided.card.storedOnFile`=**STORED** * `agreement.id` Value must be the same `agreement.id` as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs. ## Merchant-initiated installment payments {#merchant-initiated-installment-payments} You can submit installment payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer to split a single purchase into a number of payments processed at agreed intervals. In the initial CIT request, you need to provide the following fields to set up the agreement: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether you are providing the raw card details or a token (having already tokenized the card details). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source`=INTERNET Value indicates to the gateway that the transaction is cardholder initiated. * `sourceOfFunds.provided.card.storedOnFile`=TO_BE_STORED Value indicates that the payer agrees for you to store their payment details for future use. * `agreement.id` Unique value generated by you to identify a payment agreement with the payer. * `agreement.type`=INSTALLMENT Standing instruction agreement that you have established with the payer. Warning: The following fields are needed in processing a successful installment transaction: * When using API v61 and onwards: * `agreement.amountVariability` * `agreement.expiryDate` * `agreement.minimumDaysBetweenPayments` * When using API v57 - v60: * `agreement.expiryDate` * `agreement.recurring.daysBetweenPayments` In any subsequent MIT requests, you must provide the following fields: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` Value indicates to the gateway that the transaction is merchant initiated. * `transaction.source`=**MERCHANT** * `sourceOfFunds.provided.card.storedOnFile`=**STORED** * `agreement.id` Value must be the same `agreement.id` as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs. ## Merchant-initiated unscheduled payments {#merchant-initiated-unscheduled-payments} You can submit unscheduled payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer that authorizes you to initiate subsequent unscheduled payments without the payer's active participation. In the initial CIT request, you need to provide the following fields to set up the agreement: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether you are providing the raw card details or a token (having already tokenized the card details). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source`=**INTERNET** Value indicates to the gateway that the transaction is cardholder initiated. * `sourceOfFunds.provided.card.storedOnFile`=**TO_BE_STORED** Value indicates that the payer agrees for you to store their payment details for future use. * `agreement.id` Unique value generated by you to identify a payment agreement with the payer. * `agreement.type`=UNSCHEDULED Standing instruction agreement that you have established with the payer. Warning: The following fields are needed in processing a successful unscheduled transaction: * When using API v61 and onwards: * `agreement.amountVariability` * When using API v57 - v60: * `agreement.expiryDate` * `agreement.recurring.daysBetweenPayments` In any subsequent MIT requests, you must provide the following fields: * `sourceOfFunds.type`=CARD or SCHEME_TOKEN Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token). * `sourceOfFunds.provided.card.*` fields or `sourceOfFunds.token` * `transaction.source`=MERCHANT Value indicates to the gateway that the transaction is merchant initiated. * `sourceOfFunds.provided.card.storedOnFile`=STORED * `agreement.id`: The same `agreement.id` as that provided in the initial transaction. This allows the gateway to link payments in a series. Value must be the same `agreement.id` as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs. ## FAQs {#faqs} To comply with the card scheme standards for processing CITs and MITs, you must use the `sourceOfFunds.provided.card.storedOnFile` field to indicate to the gateway if the payment details are stored, not stored, or you intend to store them. For the initial CIT: * If it is a one-off payment and you do not intend to store payment details, omit the `sourceOfFunds.provided.card.storedOnFile` field in the request. * If this is the first time the payer is doing business with you, and their payment details have not been stored previously, but you now intend to store them for future use, set `sourceOfFunds.provided.card.storedOnFile`=**TO_BE_STORED**. This indicates to the gateway that the payer has agreed for you to store their payment details. Set this value irrespective of: * How you store the payment details in your own app or web site (which requires you to be PCI-compliant), or using gateway or network tokenization. * Whether you store the payment details before or after submitting the transaction to the gateway. If you are using Hosted Checkout or Hosted Session, you can store the payment details using [gateway](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/gw-tokenization/index.md) or [network](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/network-tokenization/index.md) tokenization after the initial CIT has been done and the payer has provided their payment details to the gateway. Use the CREATE OR UPDATE TOKEN operation with the relevant session ID. If you are using Direct Payment or Hosted Batch, you can store the details before or after the initial CIT is complete. * If the payer is a returning customer and you have stored their payment details earlier for a different order, you have no need to store their payment details again. However, if you use the new CIT to create an agreement with the payer for future MITs related to this CIT, set `sourceOfFunds.provided.card.storedOnFile`=**TO_BE_STORED** . This indicates to the gateway that you will be using these details for future MIT transactions. For subsequent payments, set `sourceOfFunds.provided.card.storedOnFile`=**STORED** to indicate that credential on file is used in the payment. This also applies in situations when the payer returns and their stored payment details are used for a new CIT which requires no new agreement for future MITs. If you do not have a unique identifier for your agreement with the payer, you can: * Generate an agreement ID for the purpose of the interaction with the gateway. You must then store it and submit it to the gateway on all payments in the series, including the CIT. * Use an existing identifier (that you are already storing in your system), for example, the order ID for the first payment in the series. Always use an agreement ID if possible, as it is a unique value indication between you and the payer. For example, if the payer needs to renew their insurance policy, the agreement ID can be the policy number. In some situations, you may not have access to the original agreement ID. For example: * The agreement was made a long time ago and the details were not kept on record. * You are unaware of the initial agreement ID or it was made in another payment gateway. In these cases, you cannot generate a new agreement ID but need to use a reference order ID or trace ID instead. Warning: Never use agreement ID, reference order ID, and trace ID all in the same transaction. You can only include one of them, preferably the agreement ID, but if it cannot be used, then the reference order ID. Use the trace ID only if neither of the other two are available. The reference Order ID reflects the latest order within the transaction series. For example, if the transaction series consists of an initial CIT and two subsequent MITs: * Initial CIT has the order ID = 1 * First MIT has the order ID = 2 and uses the reference Order ID = 1 (as it refers to the initial CIT) * Second MIT has the order ID = 3 and uses the reference Order ID = 2 (as it refers to the first MIT, which is the latest order ID in the series) The trace ID (also called scheme transaction ID) is a unique identifier all schemes issue for each transaction processed through them. The trace ID is used to identify associated transactions, for example: * Subsequent CAPTURE transaction * Reversal of a transaction * Linked REFUND AUTHORIZATION transaction * Subsequent transaction in a series of recurring, installment, or unscheduled payments * AUTHORIZATION to be updated The schemes use different methods to generate this ID: * Mastercard generates an ID that combines: * 3-digit financial network code * Banknet Reference Number (AN6) * Transaction date (MMDD) * VISA generates an ID that is unique for each original transaction. * Amex generates an ID that is unique for each original transaction. No. If you do not intend to charge the payer when establishing a payment agreement with them, for example, in case of a magazine subscription where the first payment is scheduled in 30 days, you must submit a VERIFY request with the agreement details: * `agreement.id` * `agreement.type` The Verify transaction becomes the first CIT in the series. For any subsequent payments, use the `agreement.id` to link payments in the series. If the payer has been authenticated in the gateway using EMV 3-D Secure authentication, you can provide the authentication.transactionId from the gateway authentication result in the VERIFY Request to Link the authentication to the payment agreement. For externally authenticated transactions, see the FAQs in [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md). The payment details against an agreement can change if, for example: * Payer lost their card and was issued a new card. * Payer changed their bank. * Card had insufficient funds and the payer provided other payment details If card details have changed (except in case of reissue of expired card and network tokens), you must perform a CIT using the original agreement ID to update the payment details or gateway token before performing any MITs with the new card number. Depending on your business model, you can also decide to create a new agreement with the payer. If you are using [network tokenization](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/network-tokenization/index.md), the schemes can automatically update the card number stored against the network token in the gateway. If you processed the initial CIT outside the Mastercard Gateway, the first MIT you submit to the Gateway must establish the agreement. For the first MIT, include the following fields: * `agreement.id` * `agreement.type` * `transaction.source` = MERCHANT * `sourceOfFunds.provided.card.storedOnFile` = STORED * `transaction.acquirer.traceId` = The trace ID from the original external CIT After the Gateway processes this first MIT, the agreement details and trace ID are stored. For all subsequent MITs, only `agreement.id` is required. The field `transaction.acquirer.traceId` is not required again. #### About trace ID format {#about-trace-id-format} Visa provides the Transaction ID (TID) in the response of the first CIT. For Mastercard, trace ID is constructed from the Financial Network Code, Reference Number, and Settlement Date returned in the CIT response. If you processed the first CIT through the Mastercard Gateway, you can retrieve the required trace details from the following response fields: * Visa: * `authorizationResponse.transactionIdentifier` * Mastercard: * `authorizationResponse.financialNetworkCode` * `authorizationResponse.transactionIdentifier` * `authorizationResponse.financialNetworkDate` Note: The field `authorizationResponse.financialNetworkDate` is in the format YYYY‑MM‑DD. When constructing the Mastercard trace ID, discard the year (YYYY) portion before submitting it in the API request.