> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/guides/card-data-encryption-overview.md). # Card Data Encryption — Overview Firstoken's Inbound Routes tokenization API supports five encryption modes for submitting card data: **RSA Full**, **RSA Partial**, **RSA+AES Hybrid**, **Shopify (ECIES)**, and **TLV (DUKPT+3DES)**. {% hint style="info" %} Every Inbound Route is configured for exactly one of these five modes by the Firstoken team when the route is set up. A client never selects or signals the mode in the request — confirm which mode your route uses, then go directly to that mode's guide below. {% endhint %} ```mermaid flowchart LR A[Firstoken team configures Inbound Route] --> B{Encryption mode} B -->|RSA Full / Partial / Hybrid| C[RSA Tokenization Integration Guide] B -->|Shopify ECIES| D[Shopify ECIES Integration Guide] B -->|TLV DUKPT+3DES| E[TLV DUKPT+3DES Integration Guide] C --> F[POST to the Inbound Route] D --> F E --> F ``` ### Modes | Mode | What gets encrypted | Request body shape | Guide | | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **RSA Full** | The entire JSON payload, as one ciphertext | A bare ciphertext string | [RSA Tokenization Integration Guide](/api-docs/guides/card-data-encryption-overview/rsa-tokenization-integration-guide.md) | | **RSA Partial** | Each field independently | A JSON object, one ciphertext per field | [RSA Tokenization Integration Guide](/api-docs/guides/card-data-encryption-overview/rsa-tokenization-integration-guide.md) | | **RSA+AES Hybrid** | Fields with AES; the AES key wrapped with RSA | A JSON object with `symmetricKey` (+ optional `symmetricIv`) plus AES-ciphertext fields | [RSA Tokenization Integration Guide](/api-docs/guides/card-data-encryption-overview/rsa-tokenization-integration-guide.md) | | **Shopify (ECIES)** | The entire JSON payload, via ECDH-derived AES-256-CTR | A JSON object with `encrypted_message`, `ephemeral_public_key`, `tag` | [Shopify (ECIES) Integration Guide](/api-docs/guides/card-data-encryption-overview/shopify-ecies-integration-guide.md) | | **TLV (DUKPT+3DES)** | Track 2 card data, via a pre-shared symmetric key | A bare hex-encoded TLV string | [TLV (DUKPT+3DES) Integration Guide](/api-docs/guides/card-data-encryption-overview/tlv-dukpt+3des-integration-guide.md) | The examples across all guides use a card payload of: ```json { "cardNumber": "4111111111111111", "securityCode": "123" } ``` Field names and nesting depend on how your specific route is configured — confirm the exact field list with the Firstoken team before integrating. {% hint style="warning" %} **Naming note:** "Shopify" is an internal integration label, not Shopify's published card-vaulting spec — this mode is a generic ECIES construction. Likewise, TLV mode uses proprietary tags, not standard EMV tags, to carry the DUKPT-encrypted card data. Don't look for a matching public spec from either name. {% endhint %} ### Prerequisites Before integrating, obtain from the Firstoken team the credentials for your assigned mode:
CredentialApplies toDescription
Route IDAll modesIdentifies the Inbound Route (see Create an Inbound Route)
Endpoint URLAll modeshttps://api.firstoken.co/routes/{routeId} (production) or https://api.firstoken-staging.co/routes/{routeId} (staging)
Encryption modeAll modesWhich of the five modes your route uses, and its field-level configuration (encrypted field names, AES algorithm, etc.)
RSA Public KeyRSA Full / Partial / HybridBase64-encoded RSA-2048 public key used to encrypt data (and, in hybrid mode, the AES session key)
EC Public KeyShopify (ECIES)The server's static P-256 public key (SPKI PEM), used for ECDH
Base Derivation Key (BDK) + initial KSNTLV (DUKPT+3DES)Pre-shared symmetric key material, provisioned via secure out-of-band key injection — never sent over this API
| Environment | Base URL | | ----------- | ---------------------------------- | | Production | `https://api.firstoken.co` | | Staging | `https://api.firstoken-staging.co` | ### Authentication Every request must include: | Header | Required | Description | | -------------- | -------- | -------------------------- | | `Content-Type` | Yes | Must be `application/json` | {% hint style="warning" %} The response includes an `ft-request-id` header generated by the service. Log it for traceability when contacting Firstoken support — do not send this header yourself; it is not a request parameter. {% endhint %} ### Error Handling | Status | Common cause | | ------ | --------------------------------------------------------------------------------------- | | `400` | Missing/empty required field, malformed body, missing symmetric key (hybrid mode) | | `500` | Internal server error, often caused by decryption or signature/MAC verification failure | For mode-specific troubleshooting (RSA decryption failures, ECIES MAC mismatches, DUKPT KSN sync issues), see the guide for your assigned mode. ### Security Considerations * Treat asymmetric public keys (RSA, EC) as configuration, not secrets to hardcode in source * Never log or persist any decrypted plaintext, session key, or shared secret * Log the `ft-request-id` returned in the response for traceability when contacting Firstoken support See your mode's guide for additional security considerations specific to that encryption scheme.