# Credential on File for Hosted Checkout
source: https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-checkout/integrate-gateway-features/cof-hosted-checkout/index.md
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.
Note: Credential on File is not supported on Hosted Checkout for PayPak, Verve, EFTPOS, Jaywan, and RuPay card schemes.
## Supported transactions and tokenization {#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 {#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 {#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. | N/A | 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. | N/A | 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 {#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 merchants to implement their own credential storage solutions.
* **Reduced PCI scope**: Sensitive card data is tokenized and securely stored, minimizing merchant 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 {#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:
1. Enable stored credential functionality
2. Save the card during an initial CIT
3. Use the returned token for subsequent CIT or MIT
### Enable Credential on File {#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 {#save-a-card-during-checkout}
Card storage requires you to indicate in the Hosted Checkout request that the card must be saved.
##### Example request {#example-request}
```json
{
"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 {#store-the-returned-token}
A successful card save returns a token in the response.
##### Example request {#example-request-1}
```json
{
"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 {#process-a-return-cit}
Selection of a previously saved card requires submission of the token instead of card details.
##### Example request {#example-request-2}
```json
{
"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 {#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.
##### Example request {#example-request-3}
```json
{
"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 {#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 {#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 {#example-test-card}
* **Card number**: 4111111111111111
* **Expiry date**: Any future date
* **CVV**: Any 3 digits
## Testing subsequent transactions {#testing-subsequent-transactions}
Validation of stored credential reuse requires these actions:
1. Perform an initial transaction with `saveCard` = true
2. Capture the returned `token.id`
3. 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 {#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.