Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

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

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, an agreement (such as 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

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

Subsequent Card-On-File Transaction

Transaction type must be “sale” or “auth”

“firsttxn” filed must be set and must be a valid value from initial Card-On-File transaction.

“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

  • No labels