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

{
  "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 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

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
`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.

Headers

string

required

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

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

{
  "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 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

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