> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runpayments.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server. # 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 | Type | Required | Values | Description | | ----------- | --------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cof` | String (1 char) | Yes | `"C"` or `"M"` | **Card on File indicator** `"C"` = Cardholder-Initiated Transaction `"M"` = Merchant-Initiated Transaction | | `cof_sched` | String (1 char) | Yes | `"Y"` or `"N"` | **Scheduled payment indicator** `"Y"` = Scheduled recurring payment `"N"` = One-time or unscheduled payment **Required for MIT**, optional for CIT | | `cof_perm` | String (1 char) | Optional | `"Y"` or `"N"` | **Cardholder permission indicator** `"Y"` = Cardholder gave explicit permission `"N"` = Permission not obtained Used for reporting only, defaults to `"N"` | ### Parameter Logic Matrix | Transaction Type | Customer Present? | Scheduled? | `cof` | `cof_sched` | | --------------------------------------- | ----------------- | ---------- | ----- | -------------- | | One-time purchase with saved card | Yes | No | `"C"` | `"N"` | | Customer-initiated payment from profile | Yes | No | `"C"` | `"N"` | | Account verification (\$0 auth for CIT) | Yes | No | `"C"` | `"N"` | | Account verification (\$0 auth for MIT) | No | No | `"M"` | `"N"` | | Monthly subscription charge | No | Yes | `"M"` | `"Y"` | | Annual membership renewal | No | Yes | `"M"` | `"Y"` | | Usage-based billing | No | No | `"M"` | `"N"` | | Delayed charge (split shipment) | No | No | `"M"` | `"N"` | | Failed payment retry | No | Varies | `"M"` | Match original | --- ## 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. ```json { "mid": "177203351990", "account_token": "9418594164541111", "expiration": "1225", "amount": "49.99", "currency": "USD", "order_id": "ORD-2025-001234", "capture": "Y", "cof": "c", "cof_sched": "n" } ``` **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. ```json { "mid": "177203351990", "account_token": "9418594164541111", "expiration": "1225", "amount": "29.99", "currency": "USD", "order_id": "SUB-2025-09-5678", "capture": "Y", "cof": "M", "cof_sched": "Y" } ``` **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. ```json { "mid": "177203351990", "account_token": "4111111111111111", "expiration": "1226", "amount": "0.00", "currency": "USD", "order_id": "VERIFY-2025-9012", "capture": "N", "vault": "Y", "cof": "C", "cof_sched": "N", "cof_perm": "Y" } ``` **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. ```json { "mid": "177203351990", "account_token": "9418594164541111", "expiration": "1225", "amount": "147.50", "currency": "USD", "order_id": "USAGE-2025-3456", "capture": "Y", "cof": "M", "cof_sched": "N" } ``` **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):** ```json { "mid": "177203351990", "account_token": "4111111111111111", "expiration": "1226", "amount": "75.00", "currency": "USD", "order_id": "ORD-2025-7890-PART1", "capture": "Y", "cof": "C", "cof_sched": "N" } ``` **Subsequent Charge (Customer Not Present):** ```json { "mid": "177203351990", "account_token": "9418594164541111", "expiration": "1226", "amount": "45.00", "currency": "USD", "order_id": "ORD-2025-7890-PART2", "capture": "Y", "cof": "M", "cof_sched": "N" } ``` **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: ```json { "amount": "45.00", "resp_text": "Approval", "comm_card": "N", "cvv_resp": "P", "resp_code": "000", "batch_id": "557", "avs_resp": "Y", "pos_entry": "Moto", "mid": "800000001780", "account_token": "9546584504635454", "authcode": "PPS010", "resp_proc": "RPCT", "cof": "M", "expiration": "1226", "trans_id": "272474550329", "result": "A", "card_number": "9546584504635454", "order_id": "ORD-2025-7890-PART2", "card_brand": null, "trans_date": "09/29/2025 17:58:49", "trans_type": "Sale" } ``` **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. ---