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.

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

Valid Card-On-File use cases:

• A cardholder enters and stores the card number for recurring billing

• A cardholder enters and stores the card number for completing future purchases without needing to re-enter the card number

Below are not Card-On-File use cases:

• ApplePay, GooglePay, or digital wallet solutions where card is not stored with the merchant

• Hotel/Card Rental/Airline where card is used only for the purpose of completing a single transaction

Processing Requirements

Display/Disclosure

A merchant processing Card-On-File transactions needs to meet the following display/disclosure requirements:

• When capturing PAN for the first time, a page (such as a link to cardholder agreement page that’s separate from the general terms and conditions) 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

Initial Authorization Rules

A PAN should only be stored after a valid authorization is obtained. This excludes token transfers between processors. If no transaction amount is due at the time of storing the credentials, a “zero-dollar-auth” (an authorization transaction with $0.00 as the amount) must be approved before a credential can be stored.

A PAN should not be stored if transaction is declined.

Subsequent Authorization Rules

A stored credential can be used up to 4 additional times within 16 days of initial authorization failure. If no valid authorization can be obtained, the credential should no longer be used (i.e., platforms should stop using a credential after 5 consecutive failures in authorization)

Transaction Requirements

Transaction needs to be sent with correct flag in “cofType” field. For more details, see Payrix API documentation here: https://portal.payrix.com/docs/api#txns

None Card-On-File

“cofType” should be left blank

Initial Card-On-File Transaction

Transaction type must be “sale” or “auth”

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

• Single - for a single purchase initiated by the cardholder

• Scheduled - A recurring purchase

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:

• Single - for a single purchase initiated by the cardholder using a previously stored credential

• Scheduled - for a recurring purchase

• Unscheduled - for a purchase initiated by merchant (or merchant system) without cardholder action (such as automatically replenish a balance)

Capture Requirements

The “cofType” field of a capture transaction must match the authorization transaction

References