Credential on File for Hosted Checkout
The Credential on File (CoF) functionality on the Hosted Checkout (HCO) platform allows you to securely store a customer’s payment credentials during a Hosted Checkout transaction and reuse them for future payments.
When Credential on File is enabled, Hosted Checkout generates a payment token after a successful authorization. This token represents the customer’s card details and can be used for subsequent transactions without requiring the customer to re‑enter card information.
By storing credentials securely, you can support recurring, installment, and subsequent payments, including one‑click checkout experiences. This reduces checkout friction, improves customer experience, and helps increase conversion rates, while maintaining compliance with industry standards, such as Payment Card Industry Data Security Standard (PCI DSS) and network tokenization requirements.
Supported transactions and tokenization
Credential on File supports:
- Cardholder‑initiated Transactions (CIT), where the customer actively completes the checkout process
- Merchant-initiated Transactions (MIT), including recurring and scheduled payments
- Secure tokenization, using gateway tokens or network tokens based on configuration
Card data is not exposed to you. Hosted Checkout provides a token only, which is required for all subsequent transactions.
Common scenarios
Credential on File is commonly used in these scenarios:
- Recurring subscriptions: Monthly or annual billing for digital services, memberships, utilities, or software platforms.
- Repeat purchases: Returning customers complete checkout without re‑entering card details.
- Travel and hospitality: Preauthorization at the time of booking with a later charge.
Expected field values by scenario
This section describes the expected request values for Credential on File related fields based on common checkout scenarios. These values help ensure that transactions are correctly classified and processed by issuers.
The values shown apply to INITIATE_CHECKOUT requests and depend on whether an agreement is present and whether stored credentials are reused.
| Use case | agreement.id | sourceOfFunds.provided.card.storedOnFile | transaction.source |
|---|---|---|---|
| Non‑agreement transaction (new user): You do not pass an agreement ID and you submit card details with customer consent to store the card for future use. | NA | TO_BE_STORED | INTERNET |
Non‑agreement transaction (returning user): You submit a previously generated token in the INITIATE_CHECKOUT request, based on customer consent provided earlier. |
NA | STORED | INTERNET |
Agreement transaction (new user): The customer submits an agreement ID together with card details in the INITIATE_CHECKOUT request. |
YES | TO_BE_STORED | INTERNET |
Agreement transaction (returning user): You submit both the token and agreement details in the INITIATE_CHECKOUT request, based on customer consent provided earlier. |
YES | TO_BE_STORED | INTERNET |
Benefits
Implementing Credential on File provides operational and commercial benefits for you.
- Improved customer experience: Returning customers complete payments more quickly, reducing checkout friction.
- Higher conversion rates: A reduced number of payment fields helps lower checkout abandonment.
- Support for subscription models: Recurring revenue models are enabled without requiring you to implement their own credential storage solutions.
- Reduced PCI scope: Sensitive card data is tokenized and securely stored, minimizing your exposure to PCI requirements.
- Improved authorization performance: When transactions are correctly flagged as stored credentials, issuers can process payments more accurately.
Using Credential on File
This section describes how to enable Credential on File, save a customer’s card during a Hosted Checkout transaction, and process subsequent payments using a stored token.
Credential on File involves these steps:
- Enable stored credential functionality
- Save the card during an initial CIT
- Use the returned token for subsequent CIT or MIT
Enable Credential on File
Use of Credential on File requires you to be enabled for:
- Tokenization
- Stored credential transactions
- MIT for recurring or unscheduled charges
If Credential on File is not enabled for you, save card requests do not generate a token.
To activate this capability, contact your account manager or regional support team.
Save a card during checkout
Card storage requires you to indicate in the Hosted Checkout request that the card must be saved.
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "WEBSITE",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "Your Merchant",
"url": "https://www.your.site.url.com"
},
"saveCardForCredentialOnFile": "PAYER_INITIATED_PAYMENTS",
}
}
Setting saveCard to true with a successful authorization results in:
- Generation of a payment token
- Return of the token in the response
- Classification of the transaction as the initial stored credential transaction
Setting saveCard to false, or omitting the field, results in:
- Processing of the transaction as a standard payment
- No token generation
The initial transaction is required to be a CIT.
Store the returned token
A successful card save returns a token in the response.
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "WEBSITE",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "JK Enterprises LLC",
"url": "https://www.your.site.url.com"
},
"saveCardForCredentialOnFile": "PAYER_INITIATED_PAYMENTS",
"tokens": [
"9855904494704968"
]
}
}
This token serves as an example.
You are required to store the token.id securely.
The token is required for all future payments and replaces card details.
Card data is not returned and must not be stored.
Process a Return CIT
Selection of a previously saved card requires submission of the token instead of card details.
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "WEBSITE",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "JK Enterprises LLC",
"url": "https://www.your.site.url.com"
},
"saveCardForCredentialOnFile": "PAYER_INITIATED_PAYMENTS",
"tokens": [
"9855904494704968"
]
}
}
This token serves as an example.
This request indicates:
- Use of stored credentials
- Active customer participation in checkout
Correct stored credential indicators are required to support optimal authorization performance.
Process an MIT
MIT involves charges initiated by you without active customer participation.
Examples include subscriptions, installment payments, and delayed charges.
A previously completed CIT is required as the reference transaction.
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "WEBSITE",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "Your Merchant",
"url": "https://www.your.site.url.com"
},
"agreement": {
"type": "RECURRING",
"id": "test",
"expiryDate": "2029-08-25",
"amountVariability": "FIXED",
"minimumDaysBetweenPayments": "29"
}
}
}
The agreement details can be modified based on your preference.
Test cards
Credential on File functionality can be validated in the Sandbox or test environment using supported test card numbers. These test cards simulate successful authorization and token generation with saveCard set to true.
Successful authorization and token creation
The test card listed here supports validation of:
- Initial CIT
- Token generation
- Subsequent CIT using a token
- MIT using a token
Example test card
- Card number: 4111111111111111
- Expiry date: Any future date
- CVV: Any 3 digits
Testing subsequent transactions
Validation of stored credential reuse requires these actions:
- Perform an initial transaction with saveCard = true
- Capture the returned token.id
- Submit a new payment request using the token
MIT validation requires:
- A successful initial CIT
- Submission of a new payment request using the token
- storedCredential.initiator set to MERCHANT
- An appropriate reason value, such as RECURRING
Simulating failure scenarios
Testing must also include these scenarios:
- Processing an MIT without a valid initial CIT
- Submitting an invalid or expired token
- Submitting a transaction without required stored credential indicators
Expected outcomes include error responses that indicate invalid token usage or missing configuration.