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

# Token Replacement to FTPS

> Replace card tokens in a document and upload the result to an FTPS server.

<Card title="File Transfer Token Replacement Guide" icon="book" href="/use-tokens/file-transfer-token-replacement">
  Replace tokens with card data in FTPS file transfers
</Card>

Performs token replacement on a file and uploads the result directly to an FTPS server. Use this when your payment processor or partner requires batch file delivery over FTPS (FTP over TLS). PCI Booking replaces all card tokens in the file body with real card data before uploading.

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid.                             |
| `-125`  | `400`       | Invalid host format (e.g. multiple colons in the server address).      |
| `-125`  | `400`       | Invalid or missing Basic Auth credentials in the Authorization header. |
| `-125`  | `400`       | The requested filter name is not recognized.                           |
| `-125`  | `400`       | Token replacement could not be applied to the file content.            |
| `-1003` | `401`       | FTPS login failed (invalid server credentials).                        |
| `-160`  | `404`       | File upload failed on the remote server.                               |

## Parameter Constraints

* **serverAddress**: Format is `hostname` or `hostname:port`. Only one colon is allowed. Default port is 22.
* **filter**: Must be one of: `GBT`, `SIMPLECSV`, `SIMPLEJSON`, `AIR`, `IUR`, `TADC`, `CSV`. Case-insensitive.
* **Authorization header**: Must contain valid Basic Auth credentials (`username:password`) for the FTPS server.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField query="accessToken" type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField query="sessionToken" type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField path="serverAddress" type="string" required>
  The FTPS server address. This can be an IP address or domain name. Add the port number with a colon if required. For example: `fsgatewaytest.aexp.com:22` or `10.200.1.10`.
</ParamField>

<ParamField path="folderPath" type="string" required>
  The folder path where the file should be uploaded to. This can be an individual folder or a full path.
</ParamField>

<ParamField path="fileName" type="string" required>
  The file name for the content being uploaded, including extension. For example: `PCIBTST.xml`.
</ParamField>

### Query String

<ParamField query="filter" type="string" required>
  Indicates the format of the file being sent. Read more on [Supported Formats](/reference/api-conventions).
</ParamField>

<ParamField query="timeout" type="string">
  The timeout, in seconds, for the FTPS server to respond.
</ParamField>

### Headers

<ParamField header="X-PciBooking-carduri" type="string" required>
  Comma-separated token values to insert into the file. Tokens should be listed in the order of their appearance. For tokens appearing multiple times, include the number of occurrences in square brackets.
</ParamField>

<ParamField header="Authorization" type="string" required>
  The authorization parameter used to authenticate to the FTPS server.
</ParamField>

<ParamField header="Content-Encoding" type="string">
  Supported compression formats: `gzip` and `deflate`. Omit this header if no compression is needed.
</ParamField>

### Request Body

The request body contains the raw file content as text. PCI Booking replaces any token placeholders with real card data (based on the `filter` format), then uploads the result to the FTPS server.

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/ftps/ftps.gateway.com:990/uploads/batch/PCIBTST.xml?filter=GBT',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
        'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
        'Content-Type': 'text/plain'
      },
      body: '<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/ftps/ftps.gateway.com:990/uploads/batch/PCIBTST.xml',
      params={'filter': 'GBT'},
      headers={
          'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
          'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
          'Content-Type': 'text/plain'
      },
      data='<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  File uploaded successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Access Token",
      "errorList": null
  }
  ```
</ResponseExample>