Card-on-File (CoF) & Recurring Payments API Guide

Owned by Katharine Unsworth (Unlicensed)
Last updated: May 03, 2022 by Miles Graves
2 min read

Basic information about using the Payrix API for card-on-file payments.

See Also: Card-On-File (CoF) Implementation Guide

When storing a payment method for subsequent recurring transactions it is important to properly identify the transaction both with the appropriate cofType field and the original authorized transaction within the firstTxns field within the txns request.

cofType and firstTxns fields are for CoF & recurring card payment only. You should skip these fields when saving an eCheck payment method.

Failure to submit both values will not identify the transaction as recurring with the Processor and increase the Risk of any subsequent recurring transaction with the token being rejected by the issuer.

In this resource we outline best practices for the following Recurring Transaction use cases:

  1. New CoF (Card-on-File)

  2. Existing CoF (Card-on-File)

  3. Imported CoF (Card-on-File)

To properly identify a transaction as recurring the following steps need to occur:

  1. An authorized transaction needs to be submitted to Payrix with CVV. If available AVS should also be included for validation. The first transaction should be submitted as traditional eComm either a $0.00 Auth or for the first recurring transaction amount. After this, all subsequent transactions will be submitted as recurring. This authorized transaction is referred to as the initial transaction.
    cofType: N/A
    origin: 2/eCommerce

  2. The card information needs to be tokenized. The token can be created after the original transaction is authorized using the card data or embedded within the authorizing transaction request.

  3. Submit subsequent recurring transactions with the token and initial transaction.
    cofType: scheduled
    origin: 2/eCommerce
    token: {Token ID}
    firstTxn: {Txn ID from Initial Transaction}

If the token creation is embedded within the authorizing transaction request and cofType is set to null, the system will automatically set this to cofType = single

If the token will always be used for recurring, set the cofType on the initial transaction to cofType = scheduled

If embedding the token creation request it is important to delete the token if the initial transaction fails, as this will be an invalid authorization.

1. New CoF

When creating a new token for recurring billing both AVS & CVV data should be submitted within the initial transaction request.

2. Existing CoF

Existing token transactions submitted with a cofType of “scheduled” should have an initial transaction submitted within the firstTxn field. If this information is not available then a new “initial” transaction that is only identified as eCommerce (submitted without cofType) should be submitted using a $0.00 Auth.

To increase the chance of subsequent transactions processing AVS data (if available) should be provided on the txn request (unless stored on the token.customer record).

3. Imported CoF

When a transaction is imported from another Processor they do not send over the initial transaction. For this reason, even when a recurring transaction is imported a new initial transaction should be performed on the Payrix platform. After receiving the token import file an initial $0.00 Auth transaction should be submitted with each token without the cofType field. Then all subsequent transactions with the token should submit the initial transaction ID within the firstTxn field in addition to the cofType field.