> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Set CVV Retention Policy

> Define when and how the CVV on a token expires, and which destinations may consume it.

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

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## 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

<ParamField path="cardToken" type="string" required>
  The token ID as returned by one of the tokenization methods.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<ParamField header="Content-Type" type="string" default="application/json">
  Set to `application/xml` to submit the request body in XML format.
</ParamField>

### Request Body

<ParamField body="CvvEndRetentionDate" type="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.
</ParamField>

<ParamField body="CvvRetentionPolicyList" type="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](/capture-cards/cvv-retention-policy#destination-types).
</ParamField>

<ParamField body="CvvRetentionPolicyList[].DestinationType" type="string" required>
  One of: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`.
</ParamField>

<ParamField body="CvvRetentionPolicyList[].DestinationData" type="string">
  The target identifier for this destination type (e.g. hostname, user ID, IP address). Leave empty for `Owner`.
</ParamField>

<ParamField body="CvvRetentionPolicyList[].Quota" type="integer" required>
  Maximum number of times the CVV may be sent to this destination.
</ParamField>

<ParamField body="DeleteCardUponCVVCleanup" type="boolean" default="false">
  If `true`, the entire token (not just the CVV) is deleted when the retention period ends.
</ParamField>

## Request Examples

<Tabs>
  <Tab title="JSON (minimal)">
    ```json theme={null}
    {
      "CvvEndRetentionDate": "2025-12-12 12:32:45",
      "CvvRetentionPolicyList": []
    }
    ```
  </Tab>

  <Tab title="JSON (with destinations)">
    ```json theme={null}
    {
      "CvvEndRetentionDate": "2025-12-12 12:32:45",
      "DeleteCardUponCvvCleanup": true,
      "CvvRetentionPolicyList": [
        {
          "DestinationType": "HostName",
          "DestinationData": "gateway.example.com",
          "Quota": 10
        },
        {
          "DestinationType": "Owner",
          "DestinationData": "",
          "Quota": 5
        }
      ]
    }
    ```
  </Tab>

  <Tab title="XML">
    ```xml theme={null}
    <?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>
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</RequestExample>

## Response

**200** - Policy set successfully.

<ResponseExample>
  ```text 200 theme={null}
  CVV retention policy set successfully. No content returned.
  ```

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

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

  ```json 423 theme={null}
  {
      "code": -1010,
      "message": "Resource is locked for updates",
      "moreInfo": "This card does not have a Cvv",
      "errorList": null
  }
  ```
</ResponseExample>