CardOnFile Transaction Rules
About 530 wordsAbout 2 min
2025-05-29
What is CardOnFile
CardOnFile is a transaction mode used in international card stored credential scenarios to identify the transaction flow where the merchant saves and reuses card information after cardholder authorization.
The following three concepts should be distinguished:
save card / remember card details: a capability used to improve future payment experienceTokenization: a credentialization method used to store or reference reusable payment credentialsCardOnFile: a transaction mode used to identify stored credential transactions
When to use it
CardOnFile is suitable for the following scenarios:
- The first transaction needs to both complete the payment and explicitly identify the flow as a stored credential transaction
- Subsequent repeat purchases, repeated charges, or later charges at non-fixed times should continue to use the same stored credential transaction path
- The merchant plans to use the token created in the first payment for repeat purchases and needs to keep the
CardOnFilemode consistent
When it is not needed
You usually do not need to pass bizType=CardOnFile in the following scenarios:
- You only want to save card information and process later payments as regular transactions
- You only want to verify card number or card details
- You only want to bind a card and obtain a reusable credential without completing the payment in the same request
Key Rules
1. First bind-and-pay transaction
If the first transaction needs to both complete payment and be processed as a CardOnFile transaction, only the key fields related to saved-card behavior are shown below.
Hosted (prePay)
{
"merchantUserId": "USER_12345",
"bizType": "CardOnFile"
}Non-Hosted (unifiedPay)
{
"merchantUserId": "USER_12345",
"createToken": "Y",
"bizType": "CardOnFile"
}2. Subsequent token-based repeat purchase
If bizType=CardOnFile was passed in the transaction where the token was first created, subsequent repeat purchases using that token must continue to pass bizType=CardOnFile. Only the rule-related key fields are shown below:
Non-Hosted (token repeat purchase)
{
"merchantUserId": "USER_12345",
"token": "TOKEN_123456",
"bizType": "CardOnFile"
}3. Regular saved-card transaction
If the first saved-card transaction was not processed in CardOnFile mode, later payments do not need to pass this parameter by default just because the card has already been saved. In both Hosted and Non-Hosted modes, whenever you need to save the card and associate it with the same cardholder, you should pass merchantUserId. Only the key fields related to saved-card behavior are shown below.
Hosted (prePay)
{
"merchantUserId": "USER_12345"
}Non-Hosted (unifiedPay)
{
"merchantUserId": "USER_12345",
"createToken": "Y"
}Do not pass bizType=CardOnFile.
4. Card verification only
If you only need to verify card validity or card details, do not pass bizType=CardOnFile.
