---
title: Card-on-File & Recurring Billing/Subscription Architecture
description: Learn how to integrate Card-on-File, recurring billing, and subscriptions using the ZIFT API. Complete developer guide with payload examples and workflow rules.
---

[Skip to content](https://learn.zift.io/card-on-file-recurring-billing/subscription-architecture#main-content)

English

Show submenu for translations

[Submit A Support Ticket](https://learn.zift.io/kb-tickets/new?hsLang=en) [Customer portal](https://learn.zift.io/tickets-view?hsLang=en)

![Zift-logo-Color-Large-Transparent.png\]](https://learn.zift.io/hs-fs/hubfs/Zift-logo-Color-Large-Transparent.png?height=40&name=Zift-logo-Color-Large-Transparent.png)

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- [Submit A Support Ticket](https://learn.zift.io/kb-tickets/new)
- [Customer portal](https://learn.zift.io/tickets-view)
- [Back to zift.io](https://zift.io/)

[Back to zift.io](https://zift.io/)

 Search the Knowledge Base

- There are no suggestions because the search field is empty.

1. [Knowledge Base](https://learn.zift.io/?hsLang=en)
2. [Best Practices](https://learn.zift.io/best-practices?hsLang=en)

# Card-on-File & Recurring Billing/Subscription Architecture

## This developer guide provides step-by-step instructions for implementing Card-on-File (COF), automated recurring subscriptions, and incidental customer transactions using the Zift API.

### Core Concepts & Parameter Reference

ZIFT enforces strict card-network compliance (Visa, Mastercard, Discover, Amex) by using two primary fields to classify the interaction mode and cardholder authorization type. 

### Key API Fields

| **Field** | **Type** | **Allowed Values** | **Description** |
| --- | --- | --- | --- |
| `transactionModeType` | Enum | **`S`** Indicates that a transaction is going to be stored as **card-on-file** and is initiated by a cardholder. **`O`** Indicates that a transaction uses a stored card-on-file and is initiated by a merchant. **`N`** Indicates that a transaction is card-not-present and is initiated by a cardholder. **`P`** Indicates that a transaction is card-present and is initiated by a cardholder. | Establishes the type of authorization the cardholder is agreeing to and who initiates the transaction, the merchant or the cardholder. |
| `transactionCategoryType` | Enum | **`R`** (Recurring) **`I`** (Installment) | Designates the agreement structure. |
| `token` | String | String (40) | ZIFT vault identifier representing stored payment details. |
| `subscriptionCode` | Long | Long (e.g., `"GYM_MEMBERSHIP_01"`) | Unique identifier for a specific recurring agreement chain. |

### Subscription and Member Management System Integration Flow

Here is the step-by-step implementation for a software platform managing member signups, monthly billing, incidental transactions and point-of-sale merchandise sales.

#### **Step 1: Initial Membership Signup**

Scenario 1: A new member signs up online for a $50/month membership. The member enters their credit card details and agrees to ongoing monthly billing.

- **Mode:** Customer-Initiated Transaction (**CIT**) establishing an agreement (`transactionModeType = S`).
- **Requirement:** Must include `subscriptionCode` to create a dedicated network agreement chain for this membership.

#### Request Payload

```
{   "requestType": "sale",   "accountNumber": "411111******1111",  "zipCode": "12345"   "cvv": "123",   "amount": "50.00",   "transactionModeType": "S",   "transactionCategoryType": "R",   "subscriptionCode": "GYM_MEMBERSHIP_01" }
```

Scenario 2: A new member signs up online for a $50/month membership. The member enters their credit card details but you don't bill the member immediately .They are just creating their payment method.

- **Mode:** Customer-Initiated Transaction (**CIT**) establishing an agreement (`transactionModeType = S`).
- **Requirement:** Must include `subscriptionCode` to create a dedicated network agreement chain for this membership.

#### Request Payload

```
{   "requestType": "account-verification",   "accountNumber": "411111******1111",  "zipCode": "12345"   "cvv": "123",   "amount": "50.00",   "transactionModeType": "S",   "transactionCategoryType": "R",   "subscriptionCode": "GYM_MEMBERSHIP_01" }
```

#### Zift Token Behavior

1. ZIFT processes the authorization and generates a `token`.
2. The `token` is returned in the response and can be used to reference the card on file.

#### **Step 2: Adding a Second Subscription (e.g., Sauna Pass)**

Scenario: An existing member decides to add a $20/month Sauna Pass to their account using their stored card.

- **Mode:** Customer-Initiated Transaction (CIT) establishing a new distinct billing authorization (`transactionModeType = S`).
- **Requirement:** Pass the existing `token` and a new, unique `subscriptionCode`.

#### Request Payload

```
{   "requestType": "sale",   "token": "BC_Member_Token",  "amount": "20.00",   "transactionModeType": "S",   "transactionCategoryType": "R",   "subscriptionCode": "Sauna_Pass_01" }
```

#### Zift Token Behavior

ZIFT processes the new billing authorization and links it to the existing cardholders `token` representing that particular payment method and subscription. Isolating subscriptions helps improve approval rates and can prevent banks from making Stop-Payment orders that affect all transactions you submit for the cardholder.

#### **Step 3: Monthly Automated Recurring Billing (Background Renewal)**

Scenario: On the 1st of the month, you automatically charge the member for their monthly renewal.

- **Mode:** Merchant-Initiated Transaction (MIT) (`transactionModeType = O`).
- **Requirement:** Provide `token`, `subscriptionCode`, and `transactionCategoryType = R`.

#### Request Payload

```
{   "requestType": "sale",   "token": "BC_Member_Token",  "amount": "50.00",   "transactionModeType": "O",   "transactionCategoryType": "R",   "subscriptionCode": "GYM_MEMBERSHIP_01" }
```

#### **Step 4: One-Off Point-of-Sale or Event Registration (In-Store / On-Session)**

Scenario: The member walks up to the front desk to buy a $15 protein tub or registers online for a $30 yoga seminar using their saved payment method on file.

- **Mode:** Customer-Initiated Transaction (CIT) (`transactionModeType = N`).
- **Requirement:** The customer is actively present. Do not pass `subscriptionCode` or `Category = R`.

#### Request Payload

```
{   "requestType": "sale",   "token": "BC_Member_Token",  "amount": "15.00",   "cvv": "123",   "transactionModeType": "N", }
```

#### **Step 5: Unscheduled / Usage-Based Charge (e.g., Guest Fee / Damage Fee)**

Scenario: A member brings a guest or incurs an incidental fee. The gym processes a $10 fee automatically in the background using the saved token.

- **Mode:** Unscheduled Merchant-Initiated Transaction (UCOF) (`transactionModeType = O`).
- **Requirement:** Omit `subscriptionCode`.

#### Request Payload

```
{   "requestType": "sale",   "token": "BC_Member_Token",  "amount": "10.00",   "transactionModeType": "O", }
```

### 3. Decision Matrix Cheat Sheet

Use this matrix to determine the parameters required for your integration code:

| **Integration Use Case** | **Customer Present?** | **transactionModeType** | **transactionCategoryType** | **subscriptionCode Required?** |
| --- | --- | --- | --- | --- |
| **New Subscription Signup** | **Yes** | **`S`** | **`R`** | **Yes** |
| **Automated Renewal ** | **No** | **`O`** | **`R`** | **Yes** |
| **Installment Renewal** | **No** | **`O`** | **`I`** | **Optional** |
| **Unscheduled Top-Up / Fee** | **No** | **`O`** | *Omitted* | **No** |
| **One-Click / POS Sale** | **Yes** | **`N`** or **`P`** | *Omitted* | **No** |
| **Net-New Guest Purchase** | **Yes** | **`N`** or **`P`** | *Omitted* | **No** |

[![zift](https://learn.zift.io/hs-fs/hubfs/Zift-logo-Color-Final-Transparency-3.png?width=432&height=236&name=Zift-logo-Color-Final-Transparency-3.png "zift")](https://zift.io)

Copyright © 2025 Zift, LLC

Copyright © 2026, Zift