Skip to main content

PCI Vault#

Tuna PCI Vault lets you process payment flows that involve card data without storing PAN/CVV in your own infrastructure.

In practice, Tuna acts as a secure tokenization and forwarding layer:

  • Your backend creates a session.
  • The customer device tokenizes card data directly with Tuna.
  • Your backend calls api/Proxy to forward tokenized requests to PCI-certified destinations.
  • Tuna replaces sensitive placeholders and returns the destination response verbatim.

API references:

Why this helps compliance#

With PCI Vault, cardholder data can be kept outside your storage and processing perimeter, reducing your PCI burden while preserving full payment flexibility.

Key benefits:

  • No PAN persistence in your backend systems.
  • CVV can transit when needed for authorization flows, but should never be stored.
  • Tokenized flows for one-time and saved-card journeys.
  • Controlled forwarding to PCI-certified destinations with HTTPS and optional domain allowlist enforcement.
Destination policy

Sensitive payment data may only be sent to PCI-certified entities. Tuna already has most acquirers in the destination allowlist.

If you need a new destination, contact Tuna with the entity details so we can:

  • Request/validate the PCI AOC.
  • Add the destination to the allowlist when required.

End-to-end journey#

PCI Vault sequence: backend creates session, frontend tokenizes card data, backend calls Proxy, Tuna forwards request to PCI-certified destination and returns verbatim response

Step-by-step implementation#

1. Create session in your backend#

Create a Token session using NewSession. Return only the session identifier to the client app.

2. Tokenize on frontend or customer device#

Tokenize card data using Generate directly from the frontend/app.

The result is a Tuna token (for example ct_...) that can be used instead of raw PAN in downstream requests.

3. Call Proxy from your backend#

Call Proxy with Tuna headers:

  • Tuna-AppToken: proxy authentication token.
  • Tuna-Session: session created at step 1.
  • Tuna-Forward-To: HTTPS destination URL.
  • Tuna-X-Forwarded-For (optional): client IP to be relayed as X-Forwarded-For.

Example:

curl -X POST 'https://token.tunagateway.com/api/Proxy' \
-H 'Content-Type: application/json' \
-H 'Tuna-AppToken: YOUR_APP_TOKEN' \
-H 'Tuna-Session: YOUR_SESSION_ID' \
-H 'Tuna-Forward-To: https://pci-certified-destination.example.com/payments' \
-H 'Tuna-X-Forwarded-For: 203.0.113.10' \
-d '{
"Card": {
"CardNumber": "ct_your_token_here",
"CVV": "CVV_3"
},
"Amount": 100.00,
"Currency": "BRL"
}'

4. Sensitive data replacement in Tuna#

Before forwarding, Tuna replaces tokenized sensitive fields in the payload.

Supported CVV placeholders:

  • CVV_3: use the 3-digit CVV associated with the token.
  • CVV_4: use the 4-digit CVV associated with the token (for AMEX).

If your flow already has a fresh CVV, you may send that CVV in transit. Do not store CVV.

5. Receive destination response#

Tuna returns the response body/status from the destination verbatim to your backend.

Saved cards journey#

Tokens are associated with users and can be listed for that user/session.

Typical flow:

  • Backend creates a session.
  • Backend calls List to retrieve customer card tokens.
  • Frontend displays masked cards and asks customer CVV.
  • Frontend calls Bind to bind CVV to the selected token.
  • Backend calls Proxy.
Saved card flow: list tokens, bind CVV, proxy forward

Operational notes#

  • Tuna-Forward-To must be HTTPS.
  • Depending on your account setup, destinations may be validated against Tuna allowlists.
  • To send a custom X-Forwarded-For downstream, use Tuna-X-Forwarded-For in your Proxy request.
  • Keep all Proxy calls in your backend, never from a public client.