See Also: Card on File (CoF) & Recurring Payments API Guide

Introduction

This document provides implementation guidelines for partners and merchants using Payrix API to process Card-On-File transactions directly. A separate guide exists for partners and merchants using Payrix recurring billing engine to process Card-On-File transactions (/wiki/spaces/PE/pages/854622244 ).

A Card-On-File transaction (also called credential on file) is defined as a transaction initiated either by a cardholder or a merchant (or merchant’s system) using a Primary Account Number (PAN) previously stored, excluding scenarios where credentials are stored solely for the purpose of completing a single transaction (i.e., storing PAN with transaction for the purpose of refund or storing PAN for the purpose of processing incremental charges on a hotel portfolio).

...

• When capturing PAN for the first time, an agreement a page (such as a link to cardholder agreement page that’s separate from the general terms and conditions page) must be available to the cardholder which clearly identifies the following:

  • A truncated version of the PAN (e.g., last 4) will be stored

  • How the credential will be used

  • Expiration date of the agreement (if applicable)

  • How the cardholder will be notified if the agreement changes

• Before using the stored credential, merchant must establish an agreement with the cardholder which clearly identifies the following:

  • Merchant name

  • Merchant address/location (if applicable)

  • Transaction amount and currency

  • Taxes, surcharges (requires card brand registration) or any additional amounts

  • Cancellation / Refund policies

  • Transaction frequency or threshold (i.e., maintain a $XX balance)

• All agreements must be available to cardholder or issuers upon request

...

The transaction ID of the authorization must be stored and used in subsequent transactions (required only if card is stored outside of Payrix system, i.e., this is not needed if Payrix tokens are used to process the initial transactions)

Subsequent Card-On-File Transaction

Transaction type must be “sale” or “auth”

When the transaction is made with a full card number (i.e., the credentials are stored else where not within Payrix system), “firsttxn” filed must be set and must be a valid value from initial Card-On-File transaction. If Payrix tokens are used to process subsequent transactions, this field is optional and does not need to be sent.

“cofType” must be set to one of the following 3 values:

...