Overview

Credential on File (CoF) enables merchants to securely store customer payment credentials for future transactions, supporting recurring payments and improving checkout experiences. This guide covers implementation with the Payment API using Collect.js and Gateway.js, with special considerations for 3-D Secure (3DS) and PSD2 compliance.

PSD2 Compliance Required

For countries under PSD2 mandate requiring 3-D Secure authentication, you must use Gateway.js for proper SCA compliance.

Risk Mitigation

Following these best practices helps mitigate risk of recurring transaction declines, even in non-PSD2 regions.

Implementation Flow

Setting Up Your First Transaction

The initial transaction establishes the credential storage relationship and must be properly flagged as a "first store" transaction.

Using Collect.js Configuration

For PSD2/3DS regions, mandate a step-up challenge by setting challengeIndicator to 04:

CollectJS.configure({
    callback: (e) => {
        const options = {
            paymentToken: e.token,
            currency: 'USD',
            amount: '1000',
            email: '[email protected]',
            phone: '8008675309',
            city: 'New York',
            state: 'NY',
            address1: '123 First St.',
            country: 'US',
            firstName: 'John',
            lastName: 'Doe',
            postalCode: '60001',
            challengeIndicator: '04' // Mandatory for 3DS transactions
        }
    }
});

Payment API Request for Initial Storage

POST: /api/transact.php

# Required Parameters
security_key: '2jPu***************jkp1'
type: 'sale'
amount: '123.00'
payment_token: {INSERT_PAYMENT_TOKEN}
customer_vault: 'add_customer'
billing_method: 'recurring'
stored_credential_indicator: 'stored'
initiated_by: 'customer'

# 3DS Variables (when using Gateway.js)
cavv: {INSERT_CAVV}
xid: {INSERT_XID}
eci: {INSERT_ECI}
cardholder_auth: {INSERT_CARDHOLDER_AUTH}
three_ds_version: {INSERT_THREE_DS_VERSION}
directory_server_id: {INSERT_DIRECTORY_SERVER_ID}

Important: Store the returned transaction_id from this initial transaction - it's required for all subsequent transactions.

Compliance & Security Requirements

PSD2 & Strong Customer Authentication (SCA)

PSD2 Regions Requirements:

European Economic Area (EEA) transactions where both issuing and acquiring banks are in EEA
Requires Strong Customer Authentication (SCA)
Gateway.js mandatory for 3DS implementation

SCA Exemptions:

MIT transactions mostly exempted from 3DS
Initial transaction must pass 3DS authentication
UK/EEA customers require challenged 3DS for first transaction

Transaction ID Management

Transaction Type	Network Transaction ID Required	Notes
Initial (CIT)	Generated automatically	Store this ID for future reference
Subsequent CIT	Reference original or previous approved	Links back to authenticated transaction
MIT	Reference original CIT transaction	Proves initial customer authentication

Best Practices & Troubleshooting

Parameter Guidelines

Always Required:

stored_credential_indicator: 'stored' (initial) or 'used' (subsequent)
initiated_by: 'customer' or 'merchant'
initial_transaction_id: For all subsequent transactions

Conditional Requirements:

billing_method: Not required for unscheduled subsequent transactions
challengeIndicator: Only for initial 3DS transactions ('04')
3DS variables: Required when using Gateway.js

Common Implementation Errors

Avoiding Transaction Declines:

Using wrong initiated_by value for transaction type
Missing initial_transaction_id in subsequent transactions
Improper 3DS implementation for PSD2 regions

Security Issues:

Exposing credentials in code or logs
Not using environment variables for sensitive data
Insufficient access control implementation

Testing & Validation

Pre-Production Checklist:

Initial Transaction Testing - Verify credential storage with proper CoF indicators, confirm 3DS challenge flow for PSD2 regions, validate transaction_id storage and retrieval
CIT Transaction Testing - Test with customer present scenarios, verify 3DS authentication when required, confirm proper credential usage indicators
MIT Transaction Testing - Verify no 3DS authentication attempted, test automated recurring payment scenarios, validate proper reference to initial transaction

Quick Reference

Transaction Comparison

Aspect	Initial Transaction	Customer Initiated (CIT)	Merchant Initiated (MIT)
Customer Present	✅ Yes	✅ Yes	❌ No
3DS Required	✅ Yes (PSD2 regions)	⚠️ May be required	❌ No
Challenge Indicator	'04' (if 3DS)	'01' (default)	N/A
stored_credential_indicator	'stored'	'used'	'used'
initiated_by	'customer'	'customer'	'merchant'
CVV Collection	✅ Recommended	✅ Recommended	❌ Not applicable

Need additional support? Contact our integration team for specific implementation guidance.