Stored Credentials

For when the merchant stores the payment credentials for use later with subsequent transactions.

When the Merchant or its agent stores the credential for a single transaction or a single purchase, it's not considered a Store Credential transaction. See notes on Industry specific MIT for details.

Attention

Amex only supports Recurring MITs and Unscheduled credential on file MITs and CITs.

Concept	Description
Incremental:	An incremental authorization is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract.
Resubmission:	This is an event that occurs when the original purchase occurred but the Merchant was not able to get authorization at the time the goods or services were provided. This is only applicable to contactless transit transactions.
Delayed charges:	A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.
Reauthorization:	A reauthorization is a purchase made after the original purchase and can reflect a number of specific conditions. Common scenarios include delayed/split shipments and extended stays/rentals.
No show:	A No-show is a transaction where the merchant is enabled to charge for services which the cardholder entered into an agreement to purchase, but did not meet the terms of the agreement.
Recurring:	Transactions processed at fixed, regular intervals not to exceed one year between Transactions, representing an agreement between a cardholder and a merchant to purchase goods or services provided over a period of time.
Installment:	A single purchase of goods or services billed to a cardholder in multiple transactions over a period of time agreed by the cardholder and merchant.
Unscheduled credential on file (UCOF):	A transaction using a Stored Credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance threshold.
Cardholder initiated transaction (CIT):	Transaction where the cardholder actively participates in the transaction.
Merchant Initiated Transaction (MIT):	Any transaction that relates to a previous cardholder-initiated transaction but is conducted without the active participation of the cardholder.

New parameters:

StoredCredential. Has only one single valid value 1.
Initiator with values M for merchant, C for cardholder.
InitiationReason with values REC for recurring, INS for installment and CRE for unscheduled credential on file, INC for incremental, RES for resubmission, DEL for delayed charges, REA reauthorization and NOS for no show.

Capturing stored credentials

When capturing a Stored Credential for the first time authorization must include:

• Initiator = C (Cardholder)
• InitiationReason with appropriate value (REC for recurring, INS for installment or CRE for credential on file)
• TransType with appropriate value, other than 12
  • Can be a payment transaction or an account verification transaction
  • Rules of SCA must be applied

Notice

For each recurring or installment agreement (see T&C for MIT example below) that the cardholder enters into, a new TransLCID is required by making a first transaction where SCA rules are applied.

Initiating a subsequent transaction

When initiating a subsequent transaction using a Stored Credential authorization must include:

• TransType = 12
• Initiator = C (Cardholder) or M (Merchant)
• StoredCredential = 1

If Initiator = C, the following additional parameters are required:

• InitiationReason = CRE
• 3D parameters if applicable (CAVD, TransXID and dsTransID)

Notice

TransLCID should NOT be sent when Initiator=C

If Initiator = M, the following parameters are required:

• TransLCID from the response of the first transaction
• InitiationReason, see rules in the table below:

InitiationReason in first transaction	Allowed value for InitiationReason in subsequent transaction
REC	REC
INS	INS
CRE	CRE, INC, RES, DEL, REA or NOS

Notice

If the first transaction happened before 30th of October 2020, then the TransLCID can refer to any subsequent transaction belonging to that same recurring payment arrangement provided it also took place before 30th of October 2020.

Transaction Flow Example:

According to the example above TransLCID = 308270500687162, 308270503687777, 308270504077878 should be sent to clearing.

Examples

First transaction and subsequent MIT's

In this example a recurring (REC) contract is being setup.

1. Fully authenticated transaction (Visa)

See 3D Secure

// code is compatible with .net8 console app
using System.Web;
using Microsoft.Extensions.DependencyInjection;

var service = new ServiceCollection();
service.AddHttpClient();

var client = service.BuildServiceProvider()
    .GetService<IHttpClientFactory>()!
    .CreateClient();

var parameters = new Dictionary<string, string>
{
    { "MsgType", "0100" },
    { "MsgSenderID", "[insert your username]" },
    { "MsgSenderAP", "[insert your password]" },
    { "MsgID", "123456" },
    { "MerchantXID", "2995652ABCDEFGH" },
    { "MerchantType", "5999" },
    { "TerminalID", "18101001" },
    { "CardType", "V" },
    { "CardNumber", "4761739001010010" },
    { "CardExpDate", "2512" },
    { "TransType", "15" },
    { "TransAmount", "150" },
    { "TransCurrency", "978" },
    { "TransTime", "230101" },
    { "TransDate", "0310" },
    { "MerchantName", "CIP*Billy shoes" },
    { "MerchantCity", "London" },
    { "CAVD", "ByIzRFVmd4iZAKq7zN3u/wAAAAA=" },
    { "dsTransID", "4E192AD7-D2EF-4AD6-B2E1-460FDA4898CB" },
    { "Initiator", "C" },
    { "InitiationReason", "REC" }
};

var request = new HttpRequestMessage(HttpMethod.Post, "https://authorization.acquiring.uat.valitor.com/process")
{
    Content = new FormUrlEncodedContent(parameters)
};

HttpResponseMessage response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var content = await response.Content.ReadAsStringAsync();
    var responseParameters = System.Web.HttpUtility.ParseQueryString(content);
    // Process responseParameters here
}
else
{
    // Handle error
}

Response

MsgType=0110&MsgID=987654&ResponseCode=00&TransLCID=917345001804486&ResponseSource=I&MerchantXID=2995652ABCDEFGH&TerminalID=18101001&CardNumber=4761739001010010&TransAmount=100&TransCurrency=987&TransID=729410123456&AuthCode=135214&TransType=15

2. Subsequent MIT

Then when doing MIT subsequent transactions (TransType = 12, see Transaction types), use the TransLCID from the response of the first transaction.

// code is compatible with .net8 console app
using System.Web;
using Microsoft.Extensions.DependencyInjection;

var service = new ServiceCollection();
service.AddHttpClient();

var client = service.BuildServiceProvider()
    .GetService<IHttpClientFactory>()!
    .CreateClient();

var parameters = new Dictionary<string, string>
{
    { "MsgType", "0100" },
    { "MsgSenderID", "[insert your username]" },
    { "MsgSenderAP", "[insert your password]" },
    { "MsgID", "123456" },
    { "MerchantXID", "2995652ABCDEFGH" },
    { "MerchantType", "5999" },
    { "TerminalID", "18101001" },
    { "CardType", "V" },
    { "CardNumber", "4761739001010010" },
    { "CardExpDate", "2512" },
    { "TransType", "12" },
    { "TransAmount", "30" },
    { "TransCurrency", "978" },
    { "TransTime", "230101" },
    { "TransDate", "0410" },
    { "MerchantName", "CIP*Billy shoes" },
    { "MerchantCity", "London" },
    { "Initiator", "M" },
    { "InitiationReason", "REC" },
    { "TransLCID", "917345001804486" },
    { "StoredCredential", "1" }
};


var request = new HttpRequestMessage(HttpMethod.Post, "https://authorization.acquiring.uat.valitor.com/process")
{
    Content = new FormUrlEncodedContent(parameters)
};

HttpResponseMessage response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var content = await response.Content.ReadAsStringAsync();
    var responseParameters = System.Web.HttpUtility.ParseQueryString(content);
    // Process responseParameters here
}
else
{
    // Handle error
}

First transaction and subsequent CIT's

In this example an unscheduled credential on file contract is being setup.

1. Fully authenticated transaction (Visa)

See 3D Secure

// code is compatible with .net8 console app
using System.Web;
using Microsoft.Extensions.DependencyInjection;

var service = new ServiceCollection();
service.AddHttpClient();

var client = service.BuildServiceProvider()
    .GetService<IHttpClientFactory>()!
    .CreateClient();

var parameters = new Dictionary<string, string>
{
    { "MsgType", "0100" },
    { "MsgSenderID", "[insert your username]" },
    { "MsgSenderAP", "[insert your password]" },
    { "MsgID", "123456" },
    { "MerchantXID", "2995652ABCDEFGH" },
    { "MerchantType", "5999" },
    { "TerminalID", "18101001" },
    { "CardType", "V" },
    { "CardNumber", "4761739001010010" },
    { "CardExpDate", "2512" },
    { "TransType", "15" },
    { "TransAmount", "150" },
    { "TransCurrency", "978" },
    { "TransTime", "230101" },
    { "TransDate", "0310" },
    { "MerchantName", "CIP*Billy shoes" },
    { "MerchantCity", "London" },
    { "CAVD", "ACIzRFVmd4iZAKq7zN3u/wAAAAA=" },
    { "dsTransID", "4E192AD7-D2EF-4AD6-B2E1-460FDA4898CB" },
    { "Initiator", "C" },
    { "InitiationReason", "CRE" }
};


var request = new HttpRequestMessage(HttpMethod.Post, "https://authorization.acquiring.uat.valitor.com/process")
{
    Content = new FormUrlEncodedContent(parameters)
};

HttpResponseMessage response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var content = await response.Content.ReadAsStringAsync();
    var responseParameters = System.Web.HttpUtility.ParseQueryString(content);
    // Process responseParameters here
}
else
{
    // Handle error
}

Response of the first transaction

MsgType=0110&MsgID=987654&ResponseCode=00&TransLCID=300267421798452&ResponseSource=I&MerchantXID=2995652ABCDEFGH&TerminalID=18101001&CardNumber=4761739001010010&TransAmount=100&TransCurrency=987&TransID=729410123456&AuthCode=135214&TransType=15

2a. Fully authenticated CIT

Then when doing a fully authenticated CIT subsequent transactions, (TransType = 12, see Transaction types) send the 3D secure parameters.

// code is compatible with .net8 console app
using System.Web;
using Microsoft.Extensions.DependencyInjection;

var service = new ServiceCollection();
service.AddHttpClient();

var client = service.BuildServiceProvider()
    .GetService<IHttpClientFactory>()!
    .CreateClient();

var parameters = new Dictionary<string, string>
{
    { "MsgType", "0100" },
    { "MsgSenderID", "[insert your username]" },
    { "MsgSenderAP", "[insert your password]" },
    { "MsgID", "123456" },
    { "MerchantXID", "2995652ABCDEFGH" },
    { "MerchantType", "5999" },
    { "TerminalID", "18101001" },
    { "CardType", "V" },
    { "CardNumber", "4761739001010010" },
    { "CardExpDate", "2512" },
    { "TransType", "12" },
    { "TransAmount", "30" },
    { "TransCurrency", "978" },
    { "TransTime", "230101" },
    { "TransDate", "0410" },
    { "MerchantName", "CIP*Billy shoes" },
    { "MerchantCity", "London" },
    { "CAVD", "mZmSIiIzMwAAAA+ggmJQcAAAAAA=" },
    { "dsTransID", "4E192AD7-D2EF-4AD6-B2E1-460FDA4898CB" },
    { "Initiator", "C" },
    { "InitiationReason", "CRE" },
    { "StoredCredentials", "1" }
};


var request = new HttpRequestMessage(HttpMethod.Post, "https://authorization.acquiring.uat.valitor.com/process")
{
    Content = new FormUrlEncodedContent(parameters)
};

HttpResponseMessage response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var content = await response.Content.ReadAsStringAsync();
    var responseParameters = System.Web.HttpUtility.ParseQueryString(content);
    // Process responseParameters here
}
else
{
    // Handle error
}

2b. CIT is exempt from SCA

If the CIT can be exempt from SCA, (see SCA Exemptions), use the ScaExemption parameter with the subsequent transactions (TransType = 12, see Transaction types). Note that this can result in a soft decline and will then need að fully authenticated transaction.

// code is compatible with .net8 console app
using System.Web;
using Microsoft.Extensions.DependencyInjection;

var service = new ServiceCollection();
service.AddHttpClient();

var client = service.BuildServiceProvider()
    .GetService<IHttpClientFactory>()!
    .CreateClient();

var parameters = new Dictionary<string, string>
{
    { "MsgType", "0100" },
    { "MsgSenderID", "[insert your username]" },
    { "MsgSenderAP", "[insert your password]" },
    { "MsgID", "123456" },
    { "MerchantXID", "2995652ABCDEFGH" },
    { "MerchantType", "5999" },
    { "TerminalID", "18101001" },
    { "CardType", "V" },
    { "CardNumber", "4761739001010010" },
    { "CardExpDate", "2512" },
    { "TransType", "12" },
    { "TransAmount", "25" },
    { "TransCurrency", "978" },
    { "TransTime", "230101" },
    { "TransDate", "0410" },
    { "MerchantName", "CIP*Billy shoes" },
    { "MerchantCity", "London" },
    { "Initiator", "C" },
    { "InitiationReason", "CRE" },
    { "StoredCredentials", "1" },
    { "ScaExemption", "LOW" }
};


var request = new HttpRequestMessage(HttpMethod.Post, "https://authorization.acquiring.uat.valitor.com/process")
{
    Content = new FormUrlEncodedContent(parameters)
};

HttpResponseMessage response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var content = await response.Content.ReadAsStringAsync();
    var responseParameters = System.Web.HttpUtility.ParseQueryString(content);
    // Process responseParameters here
}
else
{
    // Handle error
}

Terms & Conditions (T&C) for MITs

It is important that the merchant informs the cardholder the T&C of the agreement they are entering into.

What the T&C can/should include: - how will the credentials be used - what is the cancellation procedure - is there an expiration date for the agreement - is there a trial period - total amount or estimate if unknown

The merchant should then provide a written copy of the T&Cs to the cardholder.