PCI Booking provides a simple, Restful, API to perform all actions regarding a credit card.

PCI Booking is made up of several application areas. This developers site contains a guide and a reference manual for each application area.

  • The guides allow software architects and designers to have a broad view on the system operation and easily pick up those components which can fit the best different application scenarios.
  • The reference manuals allow developers to have a clear understanding of which methods are available, what input parameters are required for each method and the expected results of each.

CVV Retention Policy

According to PCI Compliance regulations, the CVV cannot be stored after the card has been used (i.e. was charged). Since PCI Booking offers card storage solutions and we are not part of the process of "using" the card, the CVV Retention Policy was created to enforce how long CVVs can be stored in PCI Booking and how and where the CVV can be relayed to.

Understanding the CVV Retention Policy

The CVV Retention Policy is made up of two components:

  • The retention period end date: CVVs can be stored in PCI Booking for up to 4 years (48 months) from the date that the card was first tokenized in PCI Booking.
  • The card relay whitelist: Cards with CVV details can be relayed only to specific destinations (each token can be set to relay to up to 50 destinations).
    The relay whitelist is made up of three components per destination (see below a full list of destination types):
    • Destination Type: Indicates which type of destination this is.
      For example, HostName.
    • Destination Data: This is the destination itself.
      For example, if the destination type was HostName, then the destination data will be the URL of the destination: http://httpbin.org/post
    • Quota: The number of times the card with the CVV can be relayed to this destination (between 1 and 50 times per destination).
      • Please note, in case when using the destination GeneralProperty, the Quota value can be between 1 and 5 only.

The CVV will be deleted after either of the following occurs (the earlier of the two):

  • The retention period end date has reached
  • The card details with the CVV has been relayed to all destinations in the number of times allowed per destination.

As an additional option, customers can choose to have the full card details deleted when the CVV is set to be deleted.

Regardless of the CVV retention policy set for the token, the card details without the CVV can be sent any number of times to any destination without any limit.

CVV Retention Destination Types

Destination Type
Description
Destination Data

UPG

Used when relaying cards to payment gateways through the Universal Payment Gateway method. This Destination Type will be generic for all payment gateways.

None

HostName

Used when relaying cards through the token replacement method. This Destination Type will be accompanied by the hostname of the target URI as a Destination Data.

The host name of the target URI.
For example, if the target URI is https://httpbin.org/post, the host name would be httpbin.org.

IpAddress

Used when relaying cards back to senders through the Gateway Service. This Destination Type will be accompanied by the IP address of the approved request sender as a Destination Data.|

The IP address of the approved sender.

Owner

Used when displaying the card details through the Card Display Form in situations where the booker manages their properties outside of PCI Booking.

None

OtherMerchant

When using card display or branded portal, and there is a property associated with the card.

The property ID or the booker ID that should have access to the CVV.

SFTP

When uploading data which includes card details to a third party SFTP server.

The IP address or the hostname of the server.

otherUser

When assigning a token to another PCI Booking user in order for them to perform actions on the token.

The userID of the user that you would like to relay the token and CVV to.

GeneralProperty

When associating this token with multiple properties in PCI Booking

None

Make sure that the destinations for relay based on host names are also included in the list of relay restrictions (if one was set up).

System-wide CVV Retention Policy

When a card is tokenized, it is automatically assigned with the default, system-wide retention policy. The system-wide retention policy is:

  • CVV retention period will be set to one month.
  • The card with the CVV can be relayed only once to the first target that is used. No further relays that include the CVV will be permitted.

Setting the CVV Retention Policy

Once the card has been tokenized in PCI Booking (it is not important which method was used to tokenize the card), the Booker will have up to 60 minutes to set the CVV Retention Policy for this token. Within those first 60 minutes of the life of the token, you can set, change or remove the CVV restrictions for that token - after the 60 minutes have passed, no further changes to the CVV policy will be allowed.
The CVV Retention Policy can be set in one of two ways:

If the CVV Retention API method is not used within 60 minutes, the token will be automatically assigned with the account-wide retention policy. If the account is not set with a retention policy, PCI Booking will use the system-wide default retention policy for this token.

Changing the CVV Retention Policy

The CVV retention policy can only be set or changed during the first 60 minutes after the token has been created. During that time, you can perform the following tasks:

Deleting a destination in the retention policy can only occur within the first 60 minutes after the token has been created and only if the CVV has not yet been relayed to that destination.

Any time after 60 minutes from tokenization, the CVV retention policy for this token cannot be changed or altered.

If you must change the retention policy, we recommend you use one of these workflows:

  • Use the duplicate card method to create a new token for the same card.
    • In the duplicate card request, provide the CVV that you would like to have added to the new token.

Duplicate Token

All of the above processes will result in a duplicate token. It is your responsibility to clear the original token from the PCI Booking storage. If you do not do so, you will be charged storage fees for this token in accordance with your billing terms.

Keeping track of CVV retention policy and usage

Customers can keep up with the CVV retention policy and the usage of the CVV in one of following ways:

"Cache-Control": "no-cache"
"Pragma": "no-cache"
"Content-Type": "application/json; charset=utf-8"
"Expires": "-1"
"X-Pcibooking-CVVRetentionEndDate": "2020-04-14T15:58:14"
"X-Pcibooking-CVVUsage": "1/10"
"X-Content-Type-Options": "nosniff"
"Server": "WWW Server/1.1"
"X-XSS-Protection": "1; mode=block"
"Date": "Mon, 14 Jan 2019 15:59:04 GMT"
"Content-Length": "368
"Cache-Control": "no-cache"
"Pragma": "no-cache"
"Via": "1.1 vegur"
"Content-Length": "5915"
"Content-Type": "application/json"
"Expires": "-1"
"Access-Control-Allow-Origin": "*"
"Access-Control-Allow-Credentials": "true"
"X-Pcibooking-CVVRetentionEndDate": "2020-04-14T16:01:29"
"X-Pcibooking-CVVUsage": "1/5"
"X-Content-Type-Options": "nosniff"
"Server": "WWW Server/1.1"
"X-XSS-Protection": "1; mode=block"
"Date": "Mon, 14 Jan 2019 16:02:49 GMT

CVV Retention Policy


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.