Set CVV Retention Policy

const response = await fetch(
  'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      CvvEndRetentionDate: '2027-12-12 12:32:45',
      DeleteCardUponCvvCleanup: false,
      CvvRetentionPolicyList: [
        {
          DestinationType: 'HostName',
          DestinationData: 'gateway.example.com',
          Quota: 10
        }
      ]
    })
  }
);

console.log(response.status);

import requests

response = requests.put(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'CvvEndRetentionDate': '2027-12-12 12:32:45',
        'DeleteCardUponCvvCleanup': False,
        'CvvRetentionPolicyList': [
            {
                'DestinationType': 'HostName',
                'DestinationData': 'gateway.example.com',
                'Quota': 10
            }
        ]
    }
)

print(response.status_code)

CVV retention policy set successfully. No content returned.

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Unrecognized DestinationType in json request"
    ]
}

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This retention policy for this card cannot be modified any more",
    "errorList": null
}

PUT

api

payments

paycard

{cardToken}

cvv

Restriction

const response = await fetch(
  'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      CvvEndRetentionDate: '2027-12-12 12:32:45',
      DeleteCardUponCvvCleanup: false,
      CvvRetentionPolicyList: [
        {
          DestinationType: 'HostName',
          DestinationData: 'gateway.example.com',
          Quota: 10
        }
      ]
    })
  }
);

console.log(response.status);

import requests

response = requests.put(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'CvvEndRetentionDate': '2027-12-12 12:32:45',
        'DeleteCardUponCvvCleanup': False,
        'CvvRetentionPolicyList': [
            {
                'DestinationType': 'HostName',
                'DestinationData': 'gateway.example.com',
                'Quota': 10
            }
        ]
    }
)

print(response.status_code)

CVV retention policy set successfully. No content returned.

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Unrecognized DestinationType in json request"
    ]
}

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This retention policy for this card cannot be modified any more",
    "errorList": null
}

Define how long the CVV is retained and which destinations may use it.

CVV Retention Policy Guide

Control how long CVV data is retained and who can use it

These cvv/Restriction endpoints manage what the documentation calls the CVV retention policy and what the PCI Booking portal calls CVV Store Rules. All three names refer to the same feature.

Error Responses

Code	HTTP Status	Condition
none	`401`	API key is missing or invalid. The response body is empty.
`-1003`	`401`	Authenticated user does not have `ForceCVVRetentionPolicy` permission.
`-1003`	`401`	The token does not exist, was deleted, or does not belong to the authenticated user. See Token Not Found or Not Accessible.
`-125`	`400`	The token does not have a CVV stored.
`-179`	`400`	Request body validation failed (e.g. unrecognized `DestinationType`, invalid `DestinationData`).
`-1010`	`423`	The retention policy is locked and cannot be modified. This happens when the 60-minute update window has passed.
`-160`	`404`	No retention policy record was found for this token (`This card has no Cvv retention policy`).
`-150`	`500`	An internal system error occurred.

Parameter Constraints

CvvEndRetentionDate: If provided, must be between the current time and 4 years from now. If omitted, CvvRetentionPolicyList must be non-empty.
CvvRetentionPolicyList: Maximum 50 entries.
Quota: Must be between 1 and 50 (inclusive).
DestinationData validation depends on DestinationType:

DestinationType	DestinationData Rules
`Upg`	Leave empty.
`HostName`	Valid hostname with 2-3 dot-separated parts. Optional port number (0-65535). Stored normalized to the top-level domain (e.g. `api.stripe.com` becomes `stripe.com`) and matched against the top-level domain of the relay target.
`IpAddress`	Valid IPv4 address. Optional port number (0-65535).
`OtherMerchant`	Non-empty, valid property user ID.
`OtherUser`	Non-empty, valid booker user ID.
`SFTP`	Valid hostname or IPv4 address. Optional port number.
`Owner`	Leave empty.
`GeneralProperty`	Leave empty.
`OtpCardView`	Leave empty.

Parameters

Path Parameters

string

required

The token ID as returned by one of the tokenization methods.

Authentication

API key only. This endpoint does not accept access tokens or session tokens.

string

required

Your API key prefixed with APIKEY. Example: APIKEY your-api-key. The x-pcibooking-api-key header is also accepted. See the Authentication guide.

Headers

string

default:"application/json"

Set to application/xml to submit the request body in XML format.

Request Body

string

Date and time when the CVV expires. Format: YYYY-MM-DD HH:MM:SS. Must be between the current time and 4 years from now. Optional when CvvRetentionPolicyList is non-empty; required otherwise.

array

Destination whitelist (up to 50 entries). Each entry specifies a destination type, its data, and the number of times the CVV may be sent to it. Pass an empty array to use time-based retention only. Required when CvvEndRetentionDate is omitted. See destination types.

string

required

One of: Upg, HostName, IpAddress, Owner, OtherMerchant, SFTP, OtherUser, GeneralProperty, OtpCardView. (The type Any is managed by the system and may appear when reading a policy - do not set it manually.)

string

The target identifier for this destination type (e.g. hostname, user ID, IP address). Leave empty for Upg, Owner, GeneralProperty, and OtpCardView.

integer

required

Maximum number of times the CVV may be sent to this destination.

boolean

default:"false"

If true, the entire token (not just the CVV) is deleted when the CVV is cleared - whether by the retention date being reached or by all destination quotas being exhausted.

Request Examples

JSON (minimal)
JSON (with destinations)
XML

{
  "CvvEndRetentionDate": "2027-12-12 12:32:45",
  "CvvRetentionPolicyList": []
}

{
  "CvvEndRetentionDate": "2027-12-12 12:32:45",
  "DeleteCardUponCvvCleanup": true,
  "CvvRetentionPolicyList": [
    {
      "DestinationType": "HostName",
      "DestinationData": "gateway.example.com",
      "Quota": 10
    },
    {
      "DestinationType": "Owner",
      "DestinationData": "",
      "Quota": 5
    }
  ]
}

<?xml version="1.0"?>
<CardCvvRetentionPolicy>
    <CvvEndRetentionDate>2027-12-12T12:32:45</CvvEndRetentionDate>
    <DeleteCardUponCvvCleanup>true</DeleteCardUponCvvCleanup>
    <CvvRetentionPolicyList>
        <CvvRetentionPolicyDestination>
            <DestinationType>HostName</DestinationType>
            <DestinationData>gateway.example.com</DestinationData>
            <Quota>10</Quota>
        </CvvRetentionPolicyDestination>
    </CvvRetentionPolicyList>
</CardCvvRetentionPolicy>

const response = await fetch(
  'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      CvvEndRetentionDate: '2027-12-12 12:32:45',
      DeleteCardUponCvvCleanup: false,
      CvvRetentionPolicyList: [
        {
          DestinationType: 'HostName',
          DestinationData: 'gateway.example.com',
          Quota: 10
        }
      ]
    })
  }
);

console.log(response.status);

import requests

response = requests.put(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'CvvEndRetentionDate': '2027-12-12 12:32:45',
        'DeleteCardUponCvvCleanup': False,
        'CvvRetentionPolicyList': [
            {
                'DestinationType': 'HostName',
                'DestinationData': 'gateway.example.com',
                'Quota': 10
            }
        ]
    }
)

print(response.status_code)

Response

200 - Policy set successfully.

CVV retention policy set successfully. No content returned.

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Unrecognized DestinationType in json request"
    ]
}

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This retention policy for this card cannot be modified any more",
    "errorList": null
}

Start Here

Authentication & General

Capture Cards

Manage Tokens

Use Tokens

Additional Functions

Payments Library

Set CVV Retention Policy

CVV Retention Policy Guide

Error Responses

Parameter Constraints

Parameters

Path Parameters

Authentication

Headers

Request Body

Request Examples

Response

CVV Retention Policy Guide

​Error Responses

​Parameter Constraints

​Parameters

​Path Parameters

​Authentication

​Headers

​Request Body

​Request Examples

​Response

Error Responses

Parameter Constraints

Parameters

Path Parameters

Authentication

Headers

Request Body

Request Examples

Response