Card On File Deposits (with Tokenization)

Overview

After a customer has processed a payment authorization successfully (e.g. using Redirect or Backend2Backend Integration for initiating the first payment - see Initiate New Payment (Redirect) or Initiate New Payment (Backend2Backend)), and has agreed that the merchant can process further payments on his behalf (without the cardholder being present), then “Card On File” payments can be initiated directly via an API call.

Historically, the Card On File Deposit has been triggered with creationTypeID = 3 (API) and the (already registered) userID and paymentAccountID, without supplying again all the user and card data.

However, effective from July 1 2018 for Visa and June 12 2018 for MasterCard, for payments to PXP Financial, the initial storage of credentials must be flagged explicitly to PXP Financial before initiating the subsequent payments based on the "Card On File" credentials. Read on for more details.

❗️
PSD2 and Stored Credentials, MITs and CITs
The Stored Credentials framework introduced respectively by Visa, MasterCard, Amex and Diners allows for both Merchant Initiated Transactions (MITs) and Cardholder Initiated Transactions (CITs) to be made - depending on cardholder presence - following initial storage of credentials.
MITs in particular, are critical to PSD2. There are specific fields to use and rules to follow for both the initial and subsequent transactions which are of concern for all merchants impacted by the PSD2 SCA regulation, especially with regard to making use of the MIT out-of-scope exemption.
Of specific concern to merchant integrations is that:

Upon initial storage of credentials, SCA is required in nearly all cases (see Visa rules Callout below)

Specific details from the initial authorisation must be stored and re-used in subsequent payments

Subsequent payments will be exempt from SCA, but will also not have a liability shift at present

📘
Initial storage of a cardholder's credentials
The field UserConsentForStoredAccount in the 'specificPaymentData' section must be populated in the initiatePayment Request - see Initiate New Payment (Backend2Backend)).

🚧
Visa rules and recommendations for storing credentials
Please note the following important rules for Visa:

Visa has mandated that where credentials are being stored for future use without a purchase, an Account Status Inquiry transaction must be used - see Card Verifications for more information

The initial storage of credentials for Visa mandates SCA when a cardholder agreement is being set up for subsequent MIT payments. When an agreement is being set up for subsequent CIT payments, SCA is not required but it is highly recommended

📘
Relaxing the SCA requirement for initial storage of credentials
Please note that by default, when the field userConsentForStoredAccount is submitted in the initiatePayment request, PXP will require SCA for transactions which are in-scope of PSD2.
However by request, a merchant can request that this default SCA behaviour is relaxed. In this case the transactions will not undergo mandatory SCA, but the merchant may be prone to a higher number of soft-declines. Please see our Soft Decline section in our PSD2 Implementation Guideline for more information on how to handle these.
While this approach would align with Visa's relaxed requirement for storing credentials for future CITs (see Callout above), MasterCard still requires SCA for all transactions where credentials are stored. In order to force SCA, please refer to the Soft Decline section linked above and our Custom PSD2 Behaviour section for more information on how to manage SCA per transaction. Please note that for MasterCard, it is a requirement for in-scope PSD2 transactions to either perform SCA or to be submitted into authorisation with an exemption. All information relating to this can be found on our PSD2 implementation guideline.

As long as the above requirements are met, the subsequent Card On File Deposit can be triggered with either creationTypeID = 10 (MerchantInitiatedWithStoredAccount) or creationTypeID = 11 (UserInitiatedWithStoredAccount) and the (already registered) userID and paymentAccountID, without supplying again all the user and card data.

👍
Creation Types 10 and 11 are only for Visa, MasterCard and Amex payments
The following section examples only apply to Visa, MasterCard, Amex and Diners payments.
For other Card Schemes, please ensure to use the creationTypeID = 1 (User) for follow-up payments for stored credentials.

See the following section for examples.

Backend2Backend Integration

First time storage of Credentials

Example initiatePaymentRequest for storing credentials for the first time.

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
	<merchantTransactionID>Order99999</merchantTransactionID>
	<paymentMethodID>2</paymentMethodID>
	<amount currencyCode="EUR">100</amount>
	<userID>u12312312</userID>
	
	<userIP>127.0.0.1</userIP>
	<userSessionID>123</userSessionID>
	<creationTypeID>1</creationTypeID>

	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>some description</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
    <data xsi:type="keyStringValuePair">
			<key>CountryCode2</key>
			<value>AT</value>
		</data>
    <data xsi:type="keyBooleanValuePair">
				<key>UserConsentForStoredAccount</key>
				<value>true</value>
		</data>
	</specificPaymentData>

	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>4111111111111111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>CardVerificationCode</key>
				<value>111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>John Doe</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryMonth</key>
				<value>1</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryYear</key>
				<value>2099</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>

</initiatePaymentRequest>

Example initiatePaymentResponse for storing credentials for the first time.

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>2</key>
      <value>VISA Deposit</value>
    </paymentMethod>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <paymentID>47026705-e9e2-44c1-8f50-2b3676d60075</paymentID>
    <userID>u12312312</userID>
    <paymentProvider>
      <key>92</key>
      <value>CQRUK</value>
    </paymentProvider>
    <amount currencyCode="EUR">100.00</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
		<state>
			<id>462890c3-2803-4b9f-b741-484ee8f73db3</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2014-12-11T11:45:16.7360552Z</createdOn>
			<description>Approved or completed successfully</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>442653</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">100</baseAmount>
		<paymentDetails>
      <detail xsi:type="keyStringValuePair">
				<key>SchemeTransactionIdentifier</key>
				<value>123456789101234</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>3e27c7d9-e3d5-45df-8033-a78e66ab319e</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Merchant-initiated Card on File payment

This is a payment which is made by a merchant on behalf of a cardholder at an unscheduled interval i.e. a one-off payment being made with the stored card information some months following a period of time after the initial storage of credentials. For example, a membership renewal at a website.

The table below summarises the most important fields that are required:

Field	Description	Required
CreationTypeID	`creationTypeID=10`	Yes
UserID	Already registered `userID`	Yes
PaymentAccountID	Already registered `paymentAccountID`	Yes
SchemeReferenceTransactionIdentifier	Use the value of `SchemeTransactionIdentifier` returned in `initiatePaymentResponse` of the initial payment	Yes
SchemeSettlementDate	Use the value of `SchemeSettlementDate` returned in `initiatePaymentResponse` of the initial payment for MasterCard payments	For MasterCard
DinersRetrievalReferenceNumberOriginalTransaction	Use the value of `DinersRetrievalReferenceNumber` returned in `initiatePaymentResponse` of the initial payment for Diners payments	For Diners
IndustrySpecificMITType	The type of Merchant Initiated Transaction. Possible values: 0 - Incremental 1 - Resubmission 2 - Delayed charge 3 - Reauthorisation 4 - No show	Optional but highly recommended for Visa. Refer to the [table] (https://developer.kalixa.com/docs/card-on-file-deposits#industry-specific-mit-types) below for more information on the specific types

Example initiatePaymentRequest for a MIT with a Card on File for a Visa Deposit :

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
  <merchantTransactionID>Order99999</merchantTransactionID>
  <paymentMethodID>2</paymentMethodID>
  <amount currencyCode="EUR">100</amount>
  <userID>u12312312</userID>

  <userIP>127.0.0.1</userIP>
  <userSessionID>123</userSessionID>
  <creationTypeID>10</creationTypeID>

  <specificPaymentData>
    <data xsi:type="keyStringValuePair">
      <key>PaymentDescription</key>
      <value>some description</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>PaymentDescriptionLanguageCode</key>
      <value>en</value>
    </data>
    <data xsi:type="keyStringValuePair">
			<key>SchemeReferenceTransactionIdentifier</key>
			<value>123456789101234</value>
		</data>
  </specificPaymentData>
  <paymentAccountID>p123123121</paymentAccountID>
</initiatePaymentRequest>

Example initiatePaymentResponse:** for a Merchant-initiated Card on File Visa Deposit with creationTypeID=10 and already registered userID and paymentAccountID:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>2</key>
      <value>VISA Deposit</value>
    </paymentMethod>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <paymentID>d614bcc2-eb66-4327-85aa-b125e8cbfa1a</paymentID>
    <userID>u12312312</userID>
    <paymentProvider>
      <key>92</key>
      <value>CQRUK</value>
    </paymentProvider>
    <amount currencyCode="EUR">100</amount>
    <creationType>
      <key>10</key>
      <value>MerchantInitiatedWithStoredAccount</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>061f514a-f247-482d-858b-f511ba773604</id>
      <definition>
        <key>13</key>
        <value>AuthorisedByProvider</value>
      </definition>
      <createdOn>2014-12-11T11:40:33.0841278Z</createdOn>
      <description>Approved or completed successfully</description>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ApprovalCode</key>
          <value>106213</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">100</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
				<key>SchemeTransactionIdentifier</key>
				<value>123456789101234</value>
			</detail>
		</paymentDetails>
    <paymentAccount>
      <paymentAccountID>p123123121</paymentAccountID>
    </paymentAccount>
  </payment>
</initiatePaymentResponse>

Customer-initiated Card on File payment

This is a payment which is made by the cardholder using the stored card information following a period of time after the initial storage of credentials. For example, a product purchased directly at a website.

Example initiatePaymentRequest for a Customer-initiated Card on File Visa Deposit with creationTypeID=11 and already registered userID and paymentAccountID:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
  <merchantTransactionID>Order99999</merchantTransactionID>
  <paymentMethodID>2</paymentMethodID>
  <amount currencyCode="EUR">100</amount>
  <userID>u12312312</userID>

  <userIP>127.0.0.1</userIP>
  <userSessionID>123</userSessionID>
  <creationTypeID>11</creationTypeID>

  <specificPaymentData>
    <data xsi:type="keyStringValuePair">
      <key>PaymentDescription</key>
      <value>some description</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>PaymentDescriptionLanguageCode</key>
      <value>en</value>
    </data>
  </specificPaymentData>

  <paymentAccountID>p123123121</paymentAccountID>
</initiatePaymentRequest>

Example initiatePaymentResponse for a Card on File Visa Deposit with creationTypeID=11 and already registered userID and paymentAccountID:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>2</key>
      <value>VISA Deposit</value>
    </paymentMethod>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <paymentID>d614bcc2-eb66-4327-85aa-b125e8cbfa1a</paymentID>
    <userID>u12312312</userID>
    <paymentProvider>
      <key>92</key>
      <value>CQRUK</value>
    </paymentProvider>
    <amount currencyCode="EUR">100</amount>
    <creationType>
      <key>11</key>
      <value>UserInitiatedWithStoredAccount</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>061f514a-f247-482d-858b-f511ba773604</id>
      <definition>
        <key>13</key>
        <value>AuthorisedByProvider</value>
      </definition>
      <createdOn>2014-12-11T11:40:33.0841278Z</createdOn>
      <description>Approved or completed successfully</description>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ApprovalCode</key>
          <value>106213</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">100</baseAmount>
    <paymentDetails xsi:nil="true"/>
    <paymentAccount>
      <paymentAccountID>p123123121</paymentAccountID>
    </paymentAccount>
  </payment>
</initiatePaymentResponse>

Industry Specific MIT Types

The following table is supplementary to the MIT section above and provides more details on the different types of MIT that can be optionally flagged to indicate the type of MIT:

MIT Type	Description
Incremental	Where a cardholder agrees to pay for any service incurred over the duration of a contract. Typically seen in hotels or car rentals
Resubmission	This happens when the merchant was not able to obtain authorisation following delivery of goods and services, possibly due to insufficient cardholder funds
Delayed charge	Typically used in hotels, cruise lines and car rentals to perform supplemental account charges after original services are rendered
Reauthorisation	This is a purchase made after the original purchase and can reflect a number of scenarios such as delayed or split shipments, or extended stays/rentals
No Show	A transaction where a merchant can charge a cardholder for services which were agreed upon by the cardholder to purchase, but did not meet the terms of the agreement

Test Cases

Merchant can simulate receiving Scheme Transaction Reference data by using the below test card numbers in the initiatePayment request.

Scheme	Card Number	Returned Fields
Visa	4522947655492323	SchemeTransactionIdentifier
MasterCard	5580071186345292 5020016237300208 (Maestro)	SchemeTransactionIdentifier SchemeSettlementDate
Diners	3811111111111207	SchemeTransactionIdentifier DinersRetrievalReferenceNumber

Card On File Deposits (with Tokenization)

Overview

❗️
PSD2 and Stored Credentials, MITs and CITs

📘
Initial storage of a cardholder's credentials

🚧
Visa rules and recommendations for storing credentials

📘
Relaxing the SCA requirement for initial storage of credentials

👍
Creation Types 10 and 11 are only for Visa, MasterCard and Amex payments

Backend2Backend Integration

First time storage of Credentials

Merchant-initiated Card on File payment

Customer-initiated Card on File payment

Industry Specific MIT Types

Test Cases

Overview

❗️PSD2 and Stored Credentials, MITs and CITs

📘Initial storage of a cardholder's credentials

🚧Visa rules and recommendations for storing credentials

📘Relaxing the SCA requirement for initial storage of credentials

👍Creation Types 10 and 11 are only for Visa, MasterCard and Amex payments

Backend2Backend Integration

First time storage of Credentials

Merchant-initiated Card on File payment

Customer-initiated Card on File payment

Industry Specific MIT Types

Test Cases

❗️
PSD2 and Stored Credentials, MITs and CITs

📘
Initial storage of a cardholder's credentials

🚧
Visa rules and recommendations for storing credentials

📘
Relaxing the SCA requirement for initial storage of credentials

👍
Creation Types 10 and 11 are only for Visa, MasterCard and Amex payments