Skip to main content
PCI DSS prohibits long-term storage of CVV data. When a card is tokenized with CVV, you need a retention policy that defines how long the CVV is kept and how many times it can be used before it is automatically cleared. The maximum retention period for any policy is 4 years (48 months), and usage quotas allow up to 50 uses per destination.
A policy cannot be changed once it applies to a token. Not by you, and not by PCI Booking. This holds whichever level the policy came from: a per-token policy, your account-wide default, or the system default. The policy is the definition of when that card counts as used, and PCI DSS does not allow that definition to be rewritten after the fact.Editing your account-wide rules in the portal changes the policy applied to tokens created from that point on. It does not alter tokens that already exist.Decide the policy before you start tokenizing. See Planning Your Policy.
You cannot change a policy, but you can replace the token. Create a new token with a newly stored CVV, set the policy you want on it during its 60-minute window, then delete the old token. The effect is the same as changing the policy.Three ways to get a token with a newly stored CVV, each of which opens a fresh 60-minute window:
  • Duplicate Token - create a new token from the existing one, providing the CVV in the request.
  • Request a CVV Entry Form - have the cardholder re-enter the CVV. This duplicates the card to a new token with the CVV attached; the original token is unchanged.
  • Send a CVV Capture Form - send the cardholder a link to re-enter the CVV.
If none of these fits, contact support@pcibooking.net. We can sometimes duplicate tokens for you in bulk. Whether that is possible depends on the CVV policy currently in force on the existing tokens, so it cannot be promised in advance.
The retention policy governs the CVV only. The card details without the CVV can be sent any number of times to any destination - the policy places no limit on relays that do not include the CVV.
This feature appears under three names. The CVV retention policy in this documentation is the same thing as CVV Store Rules in the PCI Booking portal, and the same thing as the cvv/Restriction endpoints in the API reference.
Clearing the CVV does not delete the token. When the retention period ends or the usage quota is exhausted, only the CVV is removed. The token and the rest of the card data stay in place and remain usable. The token is deleted only if you enable DeleteCardUponCvvCleanup on the policy, or if you delete it yourself with Delete Token. See Token Lifetime.

​
How It Works

CVV retention is not part of the tokenization request itself. It is a separate step that happens after tokenization:
  1. Card is tokenized (via any tokenization method) with CVV included.
  2. You have 60 minutes to set a per-token CVV retention policy via the Set CVV Retention Policy endpoint.
  3. If you don’t set one, the account-wide default policy is applied automatically. If no account-wide default exists, the system default applies: the CVV is kept for one relay or one month, whichever comes first.
This applies to every tokenization method that captures CVV. After the 60-minute window closes, the policy on that token is fixed permanently. See the note at the top of this page for how to replace a token whose policy is wrong.

​
Policy Levels

​
Policy Types

​
Destination Types

A destination is a kind of use, not a place. Sending the CVV to your payment gateway is one destination; letting a hotel view it is another; relaying it to a third party’s host is another again. Each destination carries its own independent quota. They do not draw from a shared pool. A policy allowing 10 uses at Upg and 3 at Owner permits 10 charges and 3 views, not 13 uses in total. When a destination’s quota is exhausted, the CVV can no longer be used that way, while the other destinations continue until they reach their own limits. The CVV is cleared once every destination is exhausted, or the retention date is reached, whichever comes first. A use is only counted when the CVV is actually included. Anything you do with the card without the CVV counts against nothing. Per-destination policies support these destination types:
One additional destination type, Any, is managed by the system: it represents the system default applied when no other destination policy is set. It may appear when reading a token’s policy but is reserved for system use - do not set it manually.

​
Revealing the CVV

Revealing the CVV to a person - through Card Display, the card view OTP feature, or retrieval by the owner or an associated property - counts as a use against the quota of the matching destination (Owner, OtpCardView, GeneralProperty, OtherMerchant, or OtherUser). Revealing does not delete the CVV by itself: it can be revealed multiple times, up to that destination’s quota, until the retention period ends.

​
Planning Your Policy

PCI DSS says the CVV may not be stored alongside the card number once the card has been used. It does not define what “used” means, because that depends on your business. The retention policy is where you state your own definition, and because it cannot be changed afterwards, it is worth working out before you tokenize your first card.
1

Write down every point where the CVV is needed

Walk your flow end to end and list each moment the CVV actually leaves PCI Booking. Typical answers: charging the card, letting a partner view it, relaying it to a third party’s system, pushing it to an SFTP server. If the CVV is not involved, it is not on this list.
2

Map each one to a destination type

Use the table above. Charging through the Universal Payment Gateway is Upg. A hotel or property viewing the card is OtherMerchant or GeneralProperty. Your own staff viewing it is Owner. A one-time-password card view is OtpCardView. A relay to a third party’s host is HostName.
3

Decide how many times each may happen

Set the quota per destination, up to 50 each. Be realistic rather than generous: a quota of 1 is the safest position PCI-wise, but a failed charge that needs retrying will consume a use, so allow headroom for retries.
4

Decide how long the CVV may live

Set the retention date, up to 4 years. Many businesses tie this to the end of the stay, the event, or the contract, plus a buffer.
5

Set it, then verify

Apply the policy, then read it back with Get CVV Retention Policy and confirm it is what you intended, while you are still inside the 60-minute window.

​
Worked Example: A Hotel Booking

An agency books hotel rooms for guests. It charges its own service fee to the guest’s card, and it passes the card to the hotel so the hotel can take payment for the stay. The card is captured once, at booking. Its answers: With a retention date set to one month after checkout. Expressed as a request:
Note what this policy does not restrict. The agency can display the card without the CVV to its staff as often as it likes, for as long as the token exists, and can relay the card without the CVV to any destination. Only the CVV is governed.

​
Reviewing Usage

Once cards are live, check consumption rather than waiting for a failure:
  • Get CVV Retention Policy returns the policy with a Usage count per destination, so you can see exactly how much of each quota is left.
  • Every relay that uses the CVV returns X-Pcibooking-CVVUsage in the form used/quota, and X-Pcibooking-CVVRetentionEndDate. Log both. They are the cheapest early warning that a quota is set too low.
If usage is regularly running close to a quota, the fix is not to raise it on existing tokens, which is impossible, but to raise it in your account-wide default so that future tokens get the larger allowance.

​
Auto-Delete Card on CVV Expiry

You can optionally configure the policy to delete the entire card token when its CVV is cleared, using the DeleteCardUponCvvCleanup option. Use this when a token without CVV has no value in your workflow. Without this option, the token outlives its CVV and remains stored until it is deleted separately.

​
Setting the Account-Wide Default

To set a default CVV retention policy that applies automatically to all new tokens in your account:
  1. Log in to the PCI Booking portal.
  2. Navigate to Booker Settings > CVV Store Rules. You need the Policy management permission to see this menu item.
  3. Under Storage Period, set the duration that CVV is stored (e.g., 12 months). Maximum is 4 years / 48 months.
  4. Under Destinations, define the approved list of destinations where CVV can be relayed. For each destination, specify:
    • Destination type (see Destination Types above)
    • Destination value (e.g., hostname, IP address)
    • Quota (number of times the CVV can be relayed to this destination)
You can configure up to 50 different destinations. Each destination allows a quota of up to 50 relays.
If you use destination-based retention with hostnames, make sure those hostnames are also included in your relay restrictions (if configured).
Per-token policies set via the API override the account-wide default for that specific token.

​
Managing Per-Token Policies

​
CVV Policy and Duplicate Card Handling

When eliminateCardDuplication is used and you receive a card along with the CVV where the card is already stored in PCI Booking, the CVV retention policy for the existing token will be reset, and you will need to apply a new policy using Set CVV Retention Policy. If the card received does not include the CVV, the CVV retention policy of the existing token will not change.

​
Tracking CVV Usage

Relay operations that use a token’s CVV return two response headers reporting its retention state: You can also query usage at any time via Get CVV Retention Policy, which returns a usage count per destination. If the relay target is not one of the token’s destinations, or its quota is used up, the relay still goes ahead. The CVV is sent empty, no error is returned, and neither header above is present. On a relay where you expected the CVV, a missing X-Pcibooking-CVVUsage header means the CVV was not sent. Check the token’s destinations with Get CVV Retention Policy.

​
Next Steps

CVV Management

Manage CVV data within a token: check status, capture separately, or clear manually.

Capture Cards Overview

All tokenization methods.