Skip to main content
Skip table of contents

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

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

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.

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)

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.

Terms:

  • cofType is a parameter used to validate the type of Card On File transaction when using a token.

  • firstTxn is a parameter used to identify the first transaction processed through a subscription and used again to process subsequent transactions.

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

New Card on File Setup

This page outlines the necessary endpoints for creating a new "Card on File" for future transactions.

  1. Use the Tokens endpoint to create a token for storing payment information.

  2. Create a Plan to define the schedule for recurring or installment payments.

  3. Establish a Subscription to link customers to the created plan for charging.

  4. Utilize SubscriptionTokens to connect tokens with subscriptions for payment processing.

Old Info

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

  1. An authorized transaction needs to be submitted to Payrix Pro 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.

Create a Token

First, you’ll need to create a payment token with the customer’s payment information.

This particular step covers the use case of creating a brand new customer and token without a previous transaction.

To create a token while processing a card payment transaction, see Tokenization & Recurring Payments.

New Token Request

Build the body of the POST /tokens request:

CODE 
{
    "customer": {
		"first": "John",
		"last": "Doe",
        "zip": "22222"
		},
	"payment": {
		"number": "4242424242424242",
		"cvv": "123"
	},
	"expiration": "1025"
}

Parameter

Type

Required

Description

Notes

customer

object

Required

The customer object that assigns the customer to the payment method being tokenized.

These object parameters are only required for this use case.

For a list of all available parameters, see the Customers endpoint API specification.

first

string

Required

The customer’s first name.

last

string

Required

The customer’s last name.

zip

string

Required

The customer’s billing zip code.

5-10 characters max.

payment

object

Required

The customer’s payment information.

number

string

Required

The credit card number

cvv

string

Required

The 3 or 4-digit card verification value as shown on the card.

3-4 characters max.

expiration

string

Required

The 4-digit month & year expiration as shown on the card.

MM/YY format.

New Token Response

After successfully submitting the POST /tokens request, you’ll receive a response from the Payrix Pro API. See the example below:

JSON 
{
  "customer": {
    "id": "t1_cus_123abc4d567890efg1h2i34",
    "created": "2024-11-11 12:04:35.0792",
    "modified": "2024-11-11 12:04:35.0792",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "login": "t1_log_123abc4d567890efg1h2i34",
    "merchant": null,
    "first": "John",
    "middle": null,
    "last": "Doe",
    "company": null,
    "email": null,
    "fax": null,
    "phone": null,
    "country": null,
    "zip": "11111",
    "state": null,
    "city": null,
    "address2": null,
    "address1": null,
    "inactive": 0,
    "frozen": 0,
    "shippingFirst": null,
    "shippingMiddle": null,
    "shippingLast": null,
    "shippingCompany": null,
    "shippingAddress1": null,
    "shippingAddress2": null,
    "shippingCity": null,
    "shippingState": null,
    "shippingZip": null,
    "shippingCountry": null,
    "shippingPhone": null,
    "shippingFax": null,
    "custom": null,
    "authTokenCustomer": null,
    "entity": null
  },
  "payment": {
    "id": "t1_pmt_123abc4d567890efg1h2i34",
    "method": 5,
    "number": "0000",
    "routing": "0",
    "bin": "601100",
    "payment": null,
    "lastChecked": null,
    "last4": null,
    "mask": null,
    "plaidConsumerAccount": null
  },
  "id": "t1_tok_123abc4d567890efg1h2i34",
  "created": "2024-11-11 12:04:35.1111",
  "modified": "2024-11-11 12:04:35.1111",
  "creator": "t1_log_123abc4d567890efg1h2i34",
  "modifier": "t1_log_123abc4d567890efg1h2i34",
  "token": "a12bc3d4e56f789g0h1ij23kl456789",
  "expiration": "1025",
  "inactive": 0,
  "frozen": 0,
  "name": null,
  "description": null,
  "custom": null,
  "authTokenCustomer": null,
  "status": "ready",
  "origin": null,
  "entryMode": null,
  "omnitoken": null
}

For a full list of response parameter descriptions for each related object, visit the response documentation for each endpoint below:

Now you’re ready to move on to creating the plan, which you can use to configure the details for subscription payments, installment payments of a larger purchase, or some other form of recurring payment structure between Merchants and customers.

Set Up a Plan

After you've generated your token, the next step is to set up a plan. This will allow you to create a subscription, where the customer's tokenized payment method will be assigned as a subscription token.

New Plan Request

Build the body of the POST /plans request:

CODE 
{
    "name": "Recurring Payment Plan",
    "amount": "5000",
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "schedule": "3",
    "scheduleFactor": "1",
    "um": "actual",
    "type": "recurring",
    "inactive": "0",
    "frozen": "0"
}

Parameter

Type

Required

Description

Notes & Valid Values

name

string

Optional

amount

integer

Required

The amount charged in each payment of this plan.

This value is represented as an integer in cents or as a percentage depending on the um value.

Example: 5000 = $50.00 (actual) or 50.00% (percent).

merchant

ID

Required

The ID of the Merchant associated with the customer and plan.

schedule

string

Required

The measurement of the time interval associated with the scheduleFactor in this plan.

Valid Values:

  • 1 - Daily

  • 2 - Weekly

  • 3 - Monthly

  • 4 - Annually

scheduleFactor

integer

Required

The numerical value of the schedule time interval.

Example

If the schedule is set to 2 (weekly) and the scheduleFactor is also 2, this means the plan will charge the customer biweekly.

um

string

Required

The unit of measurement for the amount parameter

actual - Dollar amount

percent -

actual is best for recurring payments, while percent is ideal for installment payments spread over time, with each covering a specific percentage.

type

string

Required

Valid Values:

  • recurring - Recurring Payment plan

  • installment - Installment payment plan.

inactive

boolean

Required

frozen

boolean

Required

New Plan Response

After successfully submitting the POST /tokens request, you’ll receive a response from the Payrix Pro API. See the example below:

CODE 
{
    "id": "t1_pln_123abc4d567890efg1h2i34",
    "created": "2024-11-11 12:34:49.2953",
    "modified": "2024-11-11 12:34:49.2953",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "name": "Recurring Payment Plan",
    "description": null,
    "schedule": "3",
    "scheduleFactor": 1,
    "amount": 5000,
    "inactive": "0",
    "frozen": "0",
    "maxFailures": null,
    "type": "recurring",
    "txnDescription": null,
    "order": null,
    "billing": null,
    "um": "actual"
}

See the full list of response parameter descriptions in the Plans response API documentation.

Create a Subscription

Once you’ve set up a plan, you’ll need to create a new subscription so the payment method you’ve saved as a token (the “card on file”) can be assigned to the payment plan.

New Subscription Request

Build the POST /subscriptions request body:

JSON 
{
    "failures": "2",
    "origin": "2",
    "plan": "t1_pln_123abc4d567890efg1h2i34",
    "start": "20241112",
    "inactive": "0",
    "frozen": "0"
}

Parameter

Type

Required

Description

Notes & Valid Values

failures

integer

Required

The number of failures before the subscription stops attempting to charge the payment method.

origin

integer

Required

The origin of the transaction that will be generated through this subscription.

Valid Values:

  • 2 - Customers will be subscribing through eCommerce.

  • 3 - Customers will be subscribing by Mail Order/Telephone.

  • 4 - Customers subscribing through Apple Pay.

  • 5 - Customers subscribing through a completed 3D Secure transaction.

  • 6 - Customers subscribing through an attempted 3D Secure transaction.

  • 8 - Customers subscribing through a PayFrame.

plan

ID

Required

The ID of the plan that includes the specified payment amount and schedule.

start

integer

Required

The date when the Subscription is set to start.

The date must be an 8-digit string in the format YYYYMMDD.

Example: 20260120 for January 20, 2026.

Note: The value must represent a future date.

inactive

boolean

Required

frozen

boolean

Required

New Subscription Response

After successfully submitting the POST /subscriptions request, you’ll receive a response from the Payrix Pro API. See the example below:

JSON 
{
    "id": "t1_sbn_673286abaa76c43fa9957df",
    "created": "2024-11-11 17:35:23.7174",
    "modified": "2024-11-11 17:35:23.7174",
    "creator": "t1_log_617b1b16317575170b3c711",
    "modifier": "t1_log_617b1b16317575170b3c711",
    "plan": "t1_pln_6732403946724480017e1db",
    "start": "20241112",
    "finish": null,
    "tax": null,
    "descriptor": null,
    "inactive": "0",
    "frozen": "0",
    "failures": 2,
    "maxFailures": null,
    "origin": "2",
    "firstTxn": null,
    "txnDescription": null,
    "order": null,
    "authentication": null,
    "authenticationId": null,
    "statementEntity": null
}

See the full list of response parameter descriptions in the Plans response API documentation.

New Card on File Setup

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

Existing Card on File Usage

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

Any recurring transaction submitted that has an initial authorization without AVS/CVV is susceptible to being declined by the issuer. In these instances the partner will need to reachout to the cardholder to obtain this information and go through the process of a New CoF.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close