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"
    ]
}

{
    "code": -1003,
    "message": "Not authorized to access this resource",
    "moreInfo": "Bad or missing authorization data, expected APIKEY",
    "errorList": null
}

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This card does not have a Cvv",
    "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"
    ]
}

{
    "code": -1003,
    "message": "Not authorized to access this resource",
    "moreInfo": "Bad or missing authorization data, expected APIKEY",
    "errorList": null
}

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This card does not have a Cvv",
    "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

Error Responses

Code	HTTP Status	Condition
`-1003`	`401`	API key is missing or invalid.
`-1003`	`401`	Authenticated user does not have `ForceCVVRetentionPolicy` permission.
`-1003`	`401`	Token does not belong to the authenticated user.
`-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`	Token not found.
`-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
`HostName`	Valid hostname with 2-3 dot-separated parts. Optional port number (0-65535).
`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.

Parameters

Path Parameters

cardToken

string

required

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

Headers

Authorization

string

required

Your API key prefixed with APIKEY. Example: APIKEY your-api-key. See the Authentication guide.

Content-Type

string

default:"application/json"

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

Request Body

CvvEndRetentionDate

string

required

Date and time when the CVV expires. Format: YYYY-MM-DD HH:MM:SS. Must not exceed 48 months from the token creation date.

CvvRetentionPolicyList

array

required

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. See destination types.

CvvRetentionPolicyList[].DestinationType

string

required

One of: HostName, Owner, OtherMerchant, SFTP, OtherUser.

CvvRetentionPolicyList[].DestinationData

string

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

CvvRetentionPolicyList[].Quota

integer

required

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

DeleteCardUponCVVCleanup

boolean

default:"false"

If true, the entire token (not just the CVV) is deleted when the retention period ends.

Request Examples

JSON (minimal)
JSON (with destinations)
XML

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

{
  "CvvEndRetentionDate": "2025-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>2025-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"
    ]
}

{
    "code": -1003,
    "message": "Not authorized to access this resource",
    "moreInfo": "Bad or missing authorization data, expected APIKEY",
    "errorList": null
}

{
    "code": -1010,
    "message": "Resource is locked for updates",
    "moreInfo": "This card does not have a Cvv",
    "errorList": null
}

Clear CVV Get CVV Retention Policy

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

Headers

Request Body

Request Examples

Response

CVV Retention Policy Guide

​Error Responses

​Parameter Constraints

​Parameters

​Path Parameters

​Headers

​Request Body

​Request Examples

​Response

Error Responses

Parameter Constraints

Parameters

Path Parameters

Headers

Request Body

Request Examples

Response