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 and Amex 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
  • 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 Rule for storing credentials without a purchase

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

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 and Amex payments.

For other Card Schemes, please ensure to continue using the creationTypeID = 3 (API) 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

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 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