GuidesAPI ReferenceDiscussions
Guides

Card On File Deposits (with Tokenization)

Suggest Edits

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:

FieldDescriptionRequired
CreationTypeIDcreationTypeID=10Yes
UserIDAlready registered userIDYes
PaymentAccountIDAlready registered paymentAccountIDYes
SchemeReferenceTransactionIdentifierUse the value of SchemeTransactionIdentifier returned in initiatePaymentResponse of the initial paymentYes
SchemeSettlementDateUse the value of SchemeSettlementDate returned in initiatePaymentResponse of the initial payment for MasterCard paymentsFor MasterCard
DinersRetrievalReferenceNumberOriginalTransactionUse the value of DinersRetrievalReferenceNumber returned in initiatePaymentResponse of the initial payment for Diners paymentsFor Diners
IndustrySpecificMITTypeThe 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 TypeDescription
IncrementalWhere a cardholder agrees to pay for any service incurred over the duration of a contract. Typically seen in hotels or car rentals
ResubmissionThis happens when the merchant was not able to obtain authorisation following delivery of goods and services, possibly due to insufficient cardholder funds
Delayed chargeTypically used in hotels, cruise lines and car rentals to perform supplemental account charges after original services are rendered
ReauthorisationThis 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 ShowA 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.

SchemeCard NumberReturned Fields
Visa4522947655492323SchemeTransactionIdentifier
MasterCard5580071186345292
5020016237300208 (Maestro)		SchemeTransactionIdentifier
SchemeSettlementDate
Diners3811111111111207SchemeTransactionIdentifier
DinersRetrievalReferenceNumber

Updated 11 months ago