Card on File

Card on File Manadate

The Card on File Mandate is a new set of requirements created by Visa, Mastercard, and Discover for businesses that store cardholder payment information for use in future sales. For more information on the mandate and what constitutes a Card on File, we recommend reading this article.

Currently only merchants processing on the Worldpay platform are required to add these new properties into their sale request bodies, but all other credit card processors will be implementing the changes soon. We recommend implementing this as soon as possible to ensure your platform is compliant with the card brands.

Overview

PaySimple will automatically map the SubmissionType as either initial or subsequent based upon the inclusion of a network_transaction_id, unless is_resubmission: true is used in the request body. The PaySimple Payments API Sandbox has been set up to return a mocked network_transaction_id when amount: 5.03 is used along with a Card on File sale_type. The PaySimple Sandbox will return the same value for the network_transaction_id after each subsequent sale. In production this value can be changed by the card brands after each subsequent sale. Only the newest value needs to be retained.

For more information on all of the sale endpoint properties, see our
Payments API Reference Guide

Properties

Property	Type	Description
sale_type	string	Valid Card on File Values: `recurring`, `installment`, `on_file_customer_initiated`, `on_file_merchant_initiated`
network_transaction_id	string	Value returned by the card brand after a successful authorization when a Card on File `sale_type` is used. It should be retained and included in the request body of the subsequent sale.
is_resubmission	boolean	Overrides the SubmissionType and sets it to resubmission. To be used when attempting to reprocess a Card on File sale after the original transaction was declined due to insufficient funds after goods or services have been delivered.

Code Samples

Sample Initial Sale Request:

POST /ps/transact/card/sale

{ 
    "amount": 5.03, 
    "payment_method_token" : "vlt_2801d17055d44c5fba1d69403fe0a20e", 
    "sale_type": "installment", 
    "capture": "completed_sale", 
    "avs": "disabled", 
    "duplicate_check": "enabled", 
}

See our section on Payment Method Tokenization (as used above) for more information on vaulting cards for use with Card on File sales.

Response:

200 Success

{ 
  "transaction_id": "tx_5d51d9afba51a90ac4a1cff8", 
  "acquirer_message": "000/AP", 
  "authorization_code": "000026", 
  "approved_amount": "5.03", 
  "batch_id": 26, 
  "card": { 
    "card_brand": "mastercard", 
    "last4": "5454", 
    "expiration_month": 2, 
    "expiration_year": 2029, 
    "account_updater_options": null 
  }, 
  "avs": { 
    "postal_code": "no_match" 
  }, 
  "outcome": { 
    "result": "success", 
    "code": "1000", 
    "description": "Approved" 
    }, 
  "network_transaction_id": "b81c73a8-94e1-4936-a425-24a37da376eb" 
}

Additional Details

Card on File `sale_type` Value	Description
on_file_customer_initiated	Used when cardholder agrees to save a card on file to be used for ongoing customer-initiated sales without a regular schedule.
on_file_merchant_initiated	Used when cardholder agrees to save a card on file to be used for ongoing merchant-initiated sales without a regular schedule.
recurring	A merchant-initiated sale processed with a variable amount over regular intervals.
installment	A merchant-initiated sale processed with a fixed amount over fixed period of time.