Card-on-File & Recurring Billing/Subscription Architecture

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

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: