Card On File (COF)

Simplify future purchases by securely storing customer credentials.

Card on File (COF) refers to a payment method where the customer’s credit or debit card information is securely stored for future transactions. Instead of requiring customers to input their card details for each purchase, you can securely retain this information, creating a convenient and streamlined payment experience.

Initiating COF payments

The COF system involves two initiation types:

Customer initiated (CIT)

Customer-initiated COF payments involve the customer using their stored card details to make purchases without re-entering card information. This method is usually employed in one-click transactions and can require authentication via 3D Secure.

Merchant initiated (MIT)

Merchant-initiated COF payments are when the customer authorises you to withdraw funds from their account. These transactions are linked to the initial agreement established during the customer-initiated transaction.

Standard MIT payments

Subscriptions	Recurring payments for services like streaming or utilities.
Unscheduled COF transactions	Triggered by specific events, such as account top-ups.
Installments	Splitting a single purchase into multiple transactions scheduled at agreed-upon dates.

Specific MIT payments

Incremental	Increasing the total authorised amount if the initial amount of the pre-authorisation is insufficient.
Re-submission	Resubmitting a previously declined transaction due to insufficient funds.
Re-authorisation	Obtaining a subsequent authorisation due to the expiration of the original one.
Delayed charges	Charging additionally after the delivery of goods or services.
No-show	Charging the customer a penalty as per your cancellation policy.

Process COF payments

You can use the COF indicator to mark a transaction as initial_customer_initiated, subsequent_customer_initiated, or as unscheduled merchant initiated – merchant_unscheduled (UCOF) for the following transaction types: authorize, authorize3D, sale, and sale3D.

Below are the three supported transaction types for storing payment credentials:

`initial_customer_initiated`	Initial transaction used to store payment credentials for future customer-initiated payments while processing. Required for external tokenisation, and optional for gateway-based tokenisation.
`subsequent_customer_initiated`	Subsequent customer initiated transaction using previously stored payment credentials. Required for external tokenisation, and optional for gateway-based tokenisation.
`merchant_unscheduled`	For a UCOF transaction, the scheme transaction identifier of the initial transaction must be sent in the transaction request. For MasterCard or Maestro UCOF, the scheme settlement date in MMDD format (e.g. 1215) of the initial transaction must be sent in the transaction request.

Initial transaction

To securely store customer credentials during the initial transaction, you must include the credential_on_file parameter and set it to initial_customer_initiated; otherwise, the credentials won’t be stored.

Example request:

<payment_transaction>
  <transaction_type>sale3d</transaction_type>
  <credential_on_file>initial_customer_initiated</credential_on_file>
  <remote_ip>78.142.46.254</remote_ip>
  <transaction_id>{{$timestamp}}</transaction_id>
  <amount>500</amount>
  <currency>EUR</currency>
  <card_holder>Travis Pastrana</card_holder>
  <card_number>5555555555554444</card_number>
  <expiration_month>02</expiration_month>
  <expiration_year>2026</expiration_year>
  <cvv>123</cvv>
  <customer_email>travis.pastrana@test.com</customer_email>
  <billing_address>
    <first_name>Travis</first_name>
    <last_name>Pastrana</last_name>
    <address1>Muster Str. 12</address1>
    <zip_code>10178</zip_code>
    <city>Berlin</city>
    <country>DE</country>
  </billing_address>
  <notification_url>https://www.example.com/notification</notification_url>
  <return_success_url>http://www.example.com/success</return_success_url>
  <return_failure_url>http://www.example.com/failure</return_failure_url>
  <threeds_v2_params>
    <threeds_method>
      <callback_url>https://webhook.site/691b0351-664d-4403-bce5-18af2a3e16ea</callback_url>
    </threeds_method>
    <control>
      <device_type>browser</device_type>
      <challenge_window_size>full_screen</challenge_window_size>
      <challenge_indicator>mandate</challenge_indicator>
    </control>
    <browser>
      <accept_header>*/*</accept_header>
      <java_enabled>false</java_enabled>
      <language>en-GB</language>
      <color_depth>24</color_depth>
      <screen_height>900</screen_height>
      <screen_width>1440</screen_width>
      <time_zone_offset>-120</time_zone_offset>
      <user_agent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) 
   Chrome/78.0.3904.97Safari/537.36</user_agent>
    </browser>
  </threeds_v2_params>
</payment_transaction>

Example response:

<payment_response>
  <transaction_type>sale3d</transaction_type> 
  <status>approved</status>
  <cvv_result_code>U</cvv_result_code> 
  <authorization_code>667800</authorization_code>  
  <retrieval_reference_number>406007000308</retrieval_reference_number> 
  <scheme_response_code>00</scheme_response_code>  
  <unique_id>fa5dd02c162ac40fb9a1e4c64b2605bd</unique_id> 
  <transaction_id>1709193212</transaction_id>
  <response_code>00</response_code> 
  <technical_message>TESTMODE: No real money will be transferred!</technical_message> 
  <message>TESTMODE: No real money will be transferred!</message>
  <mode>test</mode> 
  <timestamp>2024-02-29T07:53:32Z</timestamp> 
  <descriptor>TEST_DESCRIPTOR</descriptor> 
  <amount>500</amount> 
  <currency>EUR</currency>
  <threeds> 
     <eci>00</eci> 
  </threeds> 
  <scheme_transaction_identifier>MCC998848</scheme_transaction_identifier> 
  <scheme_settlement_date>0229</scheme_settlement_date> 
</payment_response>

Subsequent transactions

To make subsequent payments using the stored COF information, you must include the credential_on_file parameter and set it to either subsequent_customer_initiated or merchant_unscheduled.

Example request:

<payment_transaction>
  <transaction_type>sale</transaction_type>
  <credential_on_file>subsequent_customer_initiated</credential_on_file>
  <sca_params>
    <exemption>low_risk</exemption>
  </sca_params>
  <remote_ip>78.142.46.254</remote_ip>
  <transaction_id>{{$timestamp}}</transaction_id>
  <amount>500</amount>
  <currency>EUR</currency>
  <card_holder>Travis Pastrana</card_holder>
  <card_number>5555555555554444</card_number>
  <expiration_month>02</expiration_month>
  <expiration_year>2026</expiration_year>
  <cvv>123</cvv>
  <customer_email>travis.pastrana@test.com</customer_email>
  <billing_address>
    <first_name>Travis</first_name>
    <last_name>Pastrana</last_name>
    <address1>Muster Str. 12</address1>
    <zip_code>10178</zip_code>
    <city>Berlin</city>
    <country>DE</country>
  </billing_address>
</payment_transaction>

Example response:

<payment_response> 
  <transaction_type>sale</transaction_type>
  <status>approved</status> 
  <cvv_result_code>U</cvv_result_code>
  <authorization_code>295715</authorization_code> 
  <retrieval_reference_number>406007000309</retrieval_reference_number> 
  <scheme_response_code>00</scheme_response_code> 
  <unique_id>6dc132ce7df7d32ac7d849cc1f680662</unique_id> 
  <transaction_id>1709193483</transaction_id> 
  <response_code>00</response_code>
  <technical_message>TESTMODE: No real money will be transferred!</technical_message> 
  <message>TESTMODE: No real money will be transferred!</message>
  <mode>test</mode>
  <timestamp>2024-02-29T07:58:03Z</timestamp> 
  <descriptor>TEST_DESCRIPTOR</descriptor>
  <amount>500</amount>
  <currency>EUR</currency> 
  <scheme_transaction_identifier>MCC998851</scheme_transaction_identifier> 
  <scheme_settlement_date>0229</scheme_settlement_date> 
</payment_response>

Was this page helpful?