Credential on File Transactions
The following sections describe how to submit cardholder-initiated and merchant-initiated transactions (CIT and MIT) to the Spring by Citi Payment Gateway in order 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 . For full examples of the requests for all scenarios, download the Postman collection.
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 FAQs.
- The above scenarios are supported from API v74 onwards.
- 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 merchant profile for gateway tokenization.
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 = CARDorSCHEME_TOKENValue depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*fields orsourceOfFunds.tokentransaction.source = INTERNETValue indicates to the gateway that the transaction is cardholder initiated. You can set the value to
INTERNET,MOTO,MAIL_ORDER,TELEPHONE_ORDER,VOICE_RESPONSE, orCALL_CENTER.sourceOfFunds.provided.card.storedOnFile = TO_BE_STOREDValue indicates that the payer agrees for you to store their payment details for future use.
INTERNET value is used. However, you should indicate the channel through which you received the payment.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 = CARDorSCHEME_TOKENValue 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 orsourceOfFunds.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 FAQs.
CITs with 3DS
The CITs can be authenticated with 3DS to identify the cardholder and prevent fraud. You can use 3DS 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 3DS authentication. For more information on both 3DS authentication in the gateway and using external authorization in payment transactions, see 3DS Authentication.
| 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 and specify the amount required for the initial payment. Step 2: Create the CIT request with the details defined in the Cardholder-initiated Payments section, and add one of the following:
|
|
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 3DS Authentication topic, use the additional fields specified in the following steps to integrate 3DS 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:
Step 3: As the CIT request, perform the VERIFY operation request and add one of the following:
If you are using the Hosted Session 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:
If you are using the Hosted Session 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 operation to have a successful recurring transaction:
- When using the API v61 or later:
- agreement.id
- agreement.type=RECURRING
- agreement.numberOfPayments
- agreement.amountVariability
- agreement.expiryDate
- agreement.paymentFrequency
- agreement.minimumDaysBetweenPayments
When using the API v57 - v60:
- agreement.id
- agreement.type=RECURRING
- agreement.expiryDate
- agreement.recurring.daysBetweenPayments
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=CARDorSCHEME_TOKENValue depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*fields orsourceOfFunds.tokentransaction.source=INTERNET, andValue indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile=TO_BE_STOREDValue indicates that the payer agrees for you to store their payment details for future use.
agreement.idUnique value generated by you to identify a payment agreement with the payer.
agreement.type=RECURRINGStanding instruction agreement that you have established with the payer.
- When using the API v61 and onwards:
agreement.numberOfPaymentsagreement.amountVariabilityagreement.expiryDateagreement.paymentFrequencyagreement.minimumDaysBetweenPayments
- When using the API v57 - v60:
agreement.expiryDateagreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type=CARDorSCHEME_TOKENValue 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 orsourceOfFunds.tokentransaction.source=MERCHANTValue indicates to the gateway that the transaction is merchant initiated.
sourceOfFunds.provided.card.storedOnFile=STOREDagreement.idValue 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
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=CARDorSCHEME_TOKENValue depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*fields orsourceOfFunds.tokentransaction.source=INTERNETValue indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile=TO_BE_STOREDValue indicates that the payer agrees for you to store their payment details for future use.
agreement.idUnique value generated by you to identify a payment agreement with the payer.
agreement.type=INSTALLMENTStanding instruction agreement that you have established with the payer.
- When using the API v61 and onwards:
agreement.numberOfPaymentsagreement.amountVariabilityagreement.expiryDateagreement.paymentFrequencyagreement.minimumDaysBetweenPayments
- When using the API v57 - v60:
agreement.expiryDateagreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type=CARDorSCHEME_TOKENValue 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 orsourceOfFunds.tokenValue indicates to the gateway that the transaction is merchant initiated.
transaction.source=MERCHANTsourceOfFunds.provided.card.storedOnFile=STOREDagreement.idValue must be the same
agreement.idas 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
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=CARDorSCHEME_TOKENValue depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*fields orsourceOfFunds.tokentransaction.source=INTERNETValue indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile=TO_BE_STOREDValue indicates that the payer agrees for you to store their payment details for future use.
agreement.idUnique value generated by you to identify a payment agreement with the payer.
agreement.type=UNSCHEDULEDStanding instruction agreement that you have established with the payer.
- When using the API v61 and onwards:
agreement.amountVariabilityagreement.paymentFrequency
- When using the API v57 - v60:
agreement.expiryDateagreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type=CARDorSCHEME_TOKENValue 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 orsourceOfFunds.tokentransaction.source=MERCHANTValue indicates to the gateway that the transaction is merchant initiated.
sourceOfFunds.provided.card.storedOnFile=STOREDagreement.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
How do I indicate to the gateway how the payment details are handled?
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.storedOnFilefield 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. You must set this value irrespective of:- How you store the payment details — in your own app or web site (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 or network 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.
What if I do not have an agreement ID?
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:
- 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.
The reference Order ID reflects the latest order within the transaction series. For example, if the transaction series consists of an initial CIT and 2 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.
Do I need to submit a payment when establishing the payment agreement?
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.idagreement.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 3DS 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 3DS Authentication.
What if the payment details for an agreement change?
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, the schemes can automatically update the card number stored against the network token in the gateway.