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 experience
• Tokenization: a credentialization method used to store or reference reusable payment credentials
• CardOnFile: 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 CardOnFile mode 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)

Key fields in bizContent

{
  "merchantUserId": "USER_12345",
  "bizType": "CardOnFile"
}

Non-Hosted (unifiedPay)

Key fields in bizContent

{
  "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)

Key fields in bizContent

{
  "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)

Key fields in bizContent

{
  "merchantUserId": "USER_12345"
}

Non-Hosted (unifiedPay)

Key fields in bizContent

{
  "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.

Integration References

• Overview and Integration Choice
• First Payment and Save Card
• Checkout Repeat Purchase (Stored Card + CVV)
• Server-side Repeat Purchase (Token Payment)

Previous pageServer-side Repeat Purchase (Token Payment)

Next pageCodeGrant