# SFTP File Processing

Firstoken's file-based card processing enables clients to deliver card data files to a Firstoken-managed SFTP server for automated batch tokenization. Once a file is uploaded, Firstoken processes it — tokenizing card numbers and returning an output file with tokens in place of raw card data.

This feature is suited for banks, payment processors, and organizations that run recurring batch payment or billing processes involving card data files.

> **Note:** File-based card processing is configured by Firstoken. Contact our **Support Team** to get started.

***

### How It Works

```mermaid
sequenceDiagram
    participant C as Client / File Source
    participant S as Firstoken SFTP Server
    participant P as Firstoken Processing Engine
    participant O as Output Folder

    C->>C: Encrypt file with Firstoken PGP public key
    C->>S: Upload encrypted file to assigned input path
    S->>P: File detected — processing triggered
    P->>P: Decrypt file
    P->>P: Parse card data fields per agreed mapping
    P->>P: Tokenize card numbers (persistent tokens)
    P->>O: Write output file with tokens replacing card data
```

The client's file source connects to the Firstoken SFTP server and uploads a PGP-encrypted file to the designated input path. Firstoken decrypts the file, processes each record according to the field mapping agreed upon during onboarding, and writes an output file to the corresponding output path. The output file mirrors the original structure, with card numbers replaced by persistent tokens.

***

### Prerequisites

Before Firstoken can configure your integration, you must provide the following:

| Item               | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| File format        | Delimited (CSV, pipe-separated, etc.) or fixed-position                                              |
| Delimiter          | If delimited: the character separating fields (e.g. `,`)                                             |
| Field mapping      | Which column or position contains card number, expiration date, cardholder name, CVV (if applicable) |
| Date format        | Format used for expiration date (e.g. `MMYY`, `YYYY-MM`)                                             |
| SSH public key     | Public key your system will use to authenticate to the SFTP server                                   |
| Preferred username | Username for your SFTP connection                                                                    |

Firstoken will provide you with:

* SFTP hostname and your assigned input and output paths
* PGP public key to encrypt files before upload

***

### Connecting to the SFTP Server

#### Endpoints

| Environment | SFTP Host                    |
| ----------- | ---------------------------- |
| Staging     | `files-staging.firstoken.co` |
| Production  | `files.firstoken.co`         |

**Port:** 22\
**Authentication:** SSH public key

#### Connecting

```bash
sftp -i your_private_key your_username@files.firstoken.co
sftp> cd /your/assigned/input/path
sftp> put your_file.gpg
```

***

### File Encryption

All files must be encrypted with the PGP public key Firstoken provides before upload. Unencrypted files will not be processed.

```bash
gpg --output your_file.gpg \
    --encrypt \
    --recipient "Firstoken - Your Company Name" \
    your_file.csv
```

The `--recipient` value matches the key identifier Firstoken shares with you during onboarding.

***

### Output File

Once processing is complete, Firstoken writes the output file to your designated output path. The output file preserves your original structure — card numbers are replaced with persistent Firstoken tokens. All other fields are returned unchanged.

If a record cannot be processed, it is written to a separate error output. Firstoken will confirm the error handling format during onboarding.

If output encryption is required, Firstoken can encrypt the output file using a PGP public key you provide. Notify Firstoken during onboarding if this is needed.

***

### FAQ

| Question                                                | Answer                                                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Can I upload multiple files at once?                    | Yes. Each file uploaded to your input path is processed independently.                                                          |
| Can I use the same input path for different file types? | No. Each file structure or process requires a separate configuration and input path. Contact Firstoken to add additional paths. |
| What happens if a file fails to decrypt?                | The file is not processed. Firstoken will notify you if an error is detected.                                                   |
| Can I test in staging before production?                | Yes. Firstoken will configure both environments if requested during onboarding.                                                 |
| How do I get started?                                   | Contact our Support Team with the information listed under Prerequisites.                                                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/guides/sftp-file-processing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.