Stored Credential Transaction Framework

Overview

This guide provides comprehensive documentation for implementing the Visa and Mastercard Stored Credential Transaction Framework in your payment application. Compliance with this mandate is required for all merchants who store customer payment information for future use.

What This Means for Your Business

If your application stores customer payment data (tokens, account numbers, or profile information) for recurring billing, subscriptions, or card-on-file transactions, you must properly identify and flag these transactions according to card network requirements.

Non-compliance may result in:

• Transaction declines
• Data integrity flags
• Financial penalties from card networks
• Loss of processing privileges

Understanding Stored Credentials

Definition

A stored credential is any payment information retained by a merchant or payment service provider to process future transactions. This includes:

• Encrypted card data in your database
• Customer profile information with saved payment methods
• Any cardholder account information used for repeat transactions

Transaction Classification

All transactions using stored credentials must be classified into one of two categories:

1. Cardholder-Initiated Transaction (CIT)

Definition: Any transaction where the cardholder actively participates in real-time.

Common Scenarios:

• Customer logs into your website and completes a purchase using saved payment info
• Customer calls support and authorizes a payment over the phone
• Customer uses a mobile app to make a one-time payment with stored card
• Customer updates their stored payment method
• Initial account verification with $0 authorization

Key Characteristic: The cardholder is present and actively authorizing the transaction at the time it occurs.

2. Merchant-Initiated Transaction (MIT)

Definition: Any transaction where the merchant processes payment without real-time cardholder participation.

Common Scenarios:

• Scheduled subscription billing
• Automatic recurring payments
• Delayed charges for split shipments
• Balance top-ups when account falls below threshold
• Unscheduled charges based on usage or services rendered
• Failed payment retry attempts

Key Characteristic: The cardholder is not actively participating when the transaction is processed.

Required API Parameters

To comply with the mandate, you must include the following parameters in your authorization requests when using stored payment credentials:

Core Parameters

Parameter Logic Matrix

Implementation Examples

Example 1: Customer Makes One-Time Purchase with Saved Card

Scenario: Returning customer logs into your e-commerce site and completes a purchase using their saved payment method.

1
{
2
  "mid": "177203351990",
3
  "account_token": "9418594164541111",
4
  "expiration": "1225",
5
  "amount": "49.99",
6
  "currency": "USD",
7
  "order_id": "ORD-2025-001234",
8
  "capture": "Y",
9
  "cof": "c",
10
  "cof_sched": "n"
11
}

Explanation:

• cof: "C" - Customer is actively participating in the transaction
• cofscheduled: "N" - This is a one-time purchase, not a scheduled recurring payment

Example 2: Monthly Subscription Billing

Scenario: Your billing system automatically charges a customer’s saved payment method for their monthly subscription.

1
{
2
  "mid": "177203351990",
3
  "account_token": "9418594164541111",
4
  "expiration": "1225",
5
  "amount": "29.99",
6
  "currency": "USD",
7
  "order_id": "SUB-2025-09-5678",
8
  "capture": "Y",
9
  "cof": "M",
10
  "cof_sched": "Y"
11
}

Explanation:

• cof: "M" - Merchant is initiating the transaction automatically
• cof_sched: "Y" - This is a scheduled recurring payment that happens on a regular interval

Example 3: Creating New Customer Profile

Scenario: New customer signs up for your service and you’re storing their payment information for future use.

1
{
2
  "mid": "177203351990",
3
  "account_token": "4111111111111111",
4
  "expiration": "1226",
5
  "amount": "0.00",
6
  "currency": "USD",
7
  "order_id": "VERIFY-2025-9012",
8
  "capture": "N",
9
  "vault": "Y",
10
  "cof": "C",
11
  "cof_sched": "N",
12
  "cof_perm": "Y"
13
}

Explanation:

• vault: "Y" - Creates a new stored profile
• cof: "C" - Customer is present during account creation
• cof_perm: "Y" - Customer explicitly agreed to store their payment info
• amount: "0.00" - Account verification only, no charge

Example 4: Usage-Based Billing

Scenario: Your SaaS platform charges customers based on actual usage at the end of each billing cycle.

1
{
2
  "mid": "177203351990",
3
  "account_token": "9418594164541111",
4
  "expiration": "1225",
5
  "amount": "147.50",
6
  "currency": "USD",
7
  "order_id": "USAGE-2025-3456",
8
  "capture": "Y",
9
  "cof": "M",
10
  "cof_sched": "N"
11
}

Explanation:

• cof: "M" - Merchant initiates based on usage metrics
• cof_sched: "N" - Amount varies and isn’t on a fixed schedule

Example 5: Split Shipment Scenario

Scenario: Customer orders multiple items, but only some are in stock. You charge for available items immediately, then charge for remaining items when they ship later.

Initial Charge (Customer Present):

1
{
2
  "mid": "177203351990",
3
  "account_token": "4111111111111111",
4
  "expiration": "1226",
5
  "amount": "75.00",
6
  "currency": "USD",
7
  "order_id": "ORD-2025-7890-PART1",
8
  "capture": "Y",
9
  "cof": "C",
10
  "cof_sched": "N"
11
}

Subsequent Charge (Customer Not Present):

1
{
2
  "mid": "177203351990",
3
  "account_token": "9418594164541111",
4
  "expiration": "1226",
5
  "amount": "45.00",
6
  "currency": "USD",
7
  "order_id": "ORD-2025-7890-PART2",
8
  "capture": "Y",
9
  "cof": "M",
10
  "cof_sched": "N"
11
}

Explanation:

• First charge uses cof: "C" because customer is present at checkout
• Second charge uses cof: "M" because it’s processed later without customer participation

API Response Handling

Success Response

When stored credential parameters are properly included, the gateway will echo back the cof value in the response:

1
{
2
    "amount": "45.00",
3
    "resp_text": "Approval",
4
    "comm_card": "N",
5
    "cvv_resp": "P",
6
    "resp_code": "000",
7
    "batch_id": "557",
8
    "avs_resp": "Y",
9
    "pos_entry": "Moto",
10
    "mid": "800000001780",
11
    "account_token": "9546584504635454",
12
    "authcode": "PPS010",
13
    "resp_proc": "RPCT",
14
    "cof": "M",
15
    "expiration": "1226",
16
    "trans_id": "272474550329",
17
    "result": "A",
18
    "card_number": "9546584504635454",
19
    "order_id": "ORD-2025-7890-PART2",
20
    "card_brand": null,
21
    "trans_date": "09/29/2025 17:58:49",
22
    "trans_type": "Sale"
23
}

Important: Always verify that the cof value returned matches what you sent in the request to ensure proper transaction tracking.

Best Practices

1. Customer Communication

Do:

• Clearly communicate when payment information will be stored
• Obtain explicit opt-in consent for recurring charges
• Provide easy cancellation options
• Send reminders before charging stored credentials

Don’t:

• Assume consent to store payment information
• Hide recurring charge terms in fine print
• Make cancellation difficult or unclear

2. Data Management

Do:

• Store only tokenized payment data, never raw card numbers
• Implement token expiration monitoring
• Update stored credentials when cards are replaced
• Maintain audit logs of all stored credential transactions

Don’t:

• Store CVV/CVC codes
• Keep expired tokens without customer notification
• Process MIT transactions without proper authorization history

3. Error Handling

Do:

• Implement retry logic for failed recurring payments
• Notify customers immediately of payment failures
• Provide self-service options to update payment methods
• Log all stored credential transaction attempts

Don’t:

• Retry failed transactions indefinitely
• Process retries without proper COF parameters
• Fail silently without customer notification

4. Compliance Monitoring

Do:

• Regularly audit transactions for proper COF parameter usage
• Monitor decline rates on stored credential transactions
• Review network bulletins for mandate updates
• Test parameter handling in sandbox regularly

Don’t:

• Assume one-time implementation is sufficient
• Ignore data integrity warnings from the gateway
• Process stored credential transactions without required parameters

Troubleshooting

Common Issues and Solutions

Issue: Transactions declining with stored credentials

Possible Causes:

• Missing cof parameter
• Incorrect cof value (using “c” when should be “m”)
• Missing cof_sched parameter for MIT transactions

Solution: Review your transaction logic and ensure all stored credential transactions include the proper parameters based on the transaction type.

Issue: Data integrity warnings from card networks

Possible Causes:

• Inconsistent use of COF parameters
• Processing MIT transactions with CIT indicators
• Missing scheduled payment flags on recurring charges

Solution: Audit recent transactions and correct your implementation to consistently use the proper parameter values. Enable logging to track COF parameter usage across all transaction types.

Issue: Gateway not returning cof in response

Possible Causes:

• Parameter not included in request
• Using legacy API version
• Processor not yet configured for mandate

Solution: Verify you’re including the cof parameter in your charge request. Confirm with your payment provider that stored credential support is enabled for your merchant account.

Issue: Uncertainty about CIT vs MIT classification

Ask yourself:

1. Is the customer actively logged in and authorizing this specific transaction right now?
   • Yes → CIT (cof: "C")
   • No → MIT (cof: "M")
2. For MIT transactions: Is this happening on a fixed, recurring schedule?
   • Yes → Scheduled (cof_sched: "Y")
   • No → Unscheduled (cof_sched: "N")

FAQ

Q: Do I need to update my integration if I don’t store customer payment information?

A: No. This mandate only applies to transactions using stored credentials. If you process one-time payments where customers enter their card information fresh each time, no changes are required.

Q: What happens if I don’t implement these changes?

A: Non-compliant recurring transactions may be declined, flagged for data integrity issues, or result in financial penalties from card networks. Continued non-compliance may affect your ability to process payments.

Q: Do I need to re-tokenize existing stored payment methods?

A: No. The gateway automatically tracks initial and subsequent transactions once you start including the COF parameters. You don’t need to regenerate or update existing tokens.

Q: Can I use the same stored token for both CIT and MIT transactions?

A: Yes. The same payment token can be used for both transaction types. The cof parameter indicates how each individual transaction is being processed, not how the token itself is classified.

Q: How do I handle failed recurring payment retries?

A: Retry attempts should use the same COF parameters as the original transaction. If the original was cof: "M" and cof_sched: "Y", retries should use the same values.

Q: Do $0 authorization transactions need COF parameters?

A: Yes, if you’re storing the payment information for future use. Use cof: "C" for customer-initiated account verification, or cof: "M" if setting up for future merchant-initiated recurring charges.

Q: What if my business model doesn’t fit neatly into CIT or MIT?

A: Apply this simple rule: If the customer is actively participating in this specific transaction at this moment, it’s CIT. If the transaction is happening automatically without the customer’s real-time involvement, it’s MIT.