Card On File Flags

When processing transactions using a stored payment token, you can specify the Card on File (COF) context via the tokenUsage field. This tells Preczn how the token is being used, allowing us to pass the correct COF flags to the downstream payment processor. Accurate COF flagging improves approval rates, ensures compliance with card network rules, and reduces the risk of disputes.

Token Usage Types

Preczn supports four tokenUsage values:

How to Use

Include the tokenUsage field inside the payment block of your transaction request, alongside a Preczn token:

{
  "type": "sale",
  "amount": 5000,
  "currency": "USD",
  "payment": {
    "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr",
    "tokenUsage": "recurring"
  }
}

📘

Important

The tokenUsage field only takes effect when sent alongside a token in the payment block. It has no effect on transactions submitted with raw card numbers or bank account details.

Default Behavior

If you omit tokenUsage when sending a token, Preczn defaults to customer (cardholder-initiated). We recommend always setting tokenUsage explicitly so the downstream processor receives the most accurate COF context for your use case.

When COF Flags Apply

COF flags are applied when all of the following are true:

1. The transaction uses a Preczn token (not a raw card number).
2. The token is a multi-use token (merchant or customer token type).
3. The token represents a card payment method (not a bank account).

Single-use tokens (such as those created from Apple Pay or Google Pay wallet transactions) are not flagged as card-on-file, since they represent one-time payment credentials rather than stored card data.

⚠️

tokenUsage is ignored in these cases

• Raw card payments — If you send tokenUsage alongside card fields (number, expiration, cvv) instead of a token, it is silently ignored.
• Bank account tokens — If the token resolves to a bank account (ACH), tokenUsage has no effect. COF flags are a card network concept and do not apply to ACH transactions.

How Preczn Maps COF Flags to Processors

Preczn translates tokenUsage into the processor-specific COF fields required by each PSP. The table below shows how each value maps:

Adyen

Checkout.com

Till Payments

Payrix

MerchantE

For MerchantE, all card-on-file transactions are flagged with card_on_file: "Yes" and account_data_source: "Y". MerchantE does not distinguish between the individual tokenUsage types.

CardPointe

CardPointe supports card-on-file indicators through the cof and cofscheduled fields on authorization requests. Preczn maps tokenUsage to these fields as follows:

Why COF Flags Matter

• Higher approval rates — Issuers are more likely to approve transactions when the COF context is accurate, especially for merchant-initiated transactions.
• Card network compliance — Visa, Mastercard, and other networks require COF indicators on stored credential transactions. Missing or incorrect flags can result in downgrades or penalties.
• Dispute protection — Properly flagged merchant-initiated transactions (recurring, installment) carry stronger chargeback protections.
• Fraud detection — Processors and issuers use COF context to calibrate fraud scoring. Accurate flags reduce false declines.

Best Practices

1. Always specify tokenUsage explicitly rather than relying on the default. This ensures the most accurate processing for your use case.
2. Use recurring for subscriptions — any fixed-schedule billing (weekly, monthly, annually) should use recurring, not merchant.
3. Use merchant for variable charges — one-off charges against a stored card (no-show fees, top-ups, usage-based billing) should use merchant.
4. Use installment for payment plans — when splitting a known total into scheduled payments, use installment.
5. Use customer for checkout flows — when the cardholder is present and actively authorizing the charge with a saved card, use customer.