Skip to main content

​
CVC Sessions

CVC sessions temporarily store CVV/CVC data separately from the card token.

​
Overview

CVV/CVC codes are:
  • Never stored with the card token
  • Stored temporarily in a separate session
  • Deleted after use (for security)
  • Required by most PSPs for card-not-present transactions

​
Session Lifecycle

​
Creating a CVC Session

CVC sessions are created automatically when you tokenize with a CVV: 
curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/tokenize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "card",
    "data": {
      "cardNumber": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvv": "123"
    }
  }'
Response: 
{
  "success": true,
  "token": "tok_a1b2c3d4e5f6",
  "cvc_session_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Session Properties

PropertyRegular TokenTest Token
TTL90 seconds1 year (test tokens)
Deleted after useYesNo
Can be reusedNoYes

​
Using a CVC Session

Include cvc_session_id in proxy requests: 
{
  "token": "tok_a1b2c3d4e5f6",
  "cvc_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "proxy_url": "https://api.stripe.com/v1/charges",
  "request_data": {
    "card": {
      "number": "${cardNumber}",
      "cvc": "${cvv}"  // Replaced from CVC session
    }
  }
}

​
Session Expiration

​
Regular Sessions (90 seconds)

{
  "success": false,
  "message": "CVC session expired or not found"
}
Solution: Re-tokenize with CVV to get a new session.

​
Test Sessions (1 year)

Test token CVC sessions last much longer for development convenience.

​
Without CVC Session

If you don’t have a CVC session:

​
Option 1: Skip CVV

Some PSPs allow transactions without CVV: 
{
  "token": "tok_a1b2c3d4e5f6",
  "proxy_url": "https://api.psp.com/charge",
  "request_data": {
    "card": {
      "number": "${cardNumber}",
      "exp_month": "${expirationMonth}",
      "exp_year": "${expirationYear}"
      // No CVV
    }
  }
}

​
Option 2: Re-tokenize

Collect CVV again and create a new session: 
curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/tokenize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "card",
    "data": {
      "cardNumber": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvv": "123"
    }
  }'
With deduplication enabled, you’ll get the same token with a new CVC session.

​
Error Responses

​
Session Not Found

{
  "success": false,
  "message": "CVC session expired or not found"
}
Causes:
  • Session expired (>90 seconds)
  • Session already used
  • Invalid session ID
  • Session from different project

​
Missing Session ID

Using ${cvv} placeholder without a CVC session: 
{
  "success": false,
  "message": "CVC session required for CVV placeholder"
}

​
Best Practices

​
1. Use CVC Sessions Promptly

The 90-second window is intentional for security. Design your flow to:
  1. Tokenize with CVV
  2. Immediately process payment
  3. Don’t store session IDs long-term

​
2. Handle Expiration Gracefully

try {
  await processPayment(token, cvcSessionId);
} catch (error) {
  if (error.message.includes('CVC session expired')) {
    // Prompt user to re-enter CVV
    const newSession = await retokenizeWithCVV();
    await processPayment(token, newSession.cvc_session_id);
  }
}

​
3. Use Test Tokens for Development

Test tokens have 1-year CVC sessions, making development easier: 
curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/test-tokens \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "card",
    "data": {
      "cardNumber": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvv": "123"
    }
  }'

​
4. Delete a session when needed

You can delete a CVC session by ID (e.g. after a successful transaction) with DELETE /proxy/delete-cvc-session/ (API key auth). See API Reference → Proxy.

​
5. Don’t Store CVC Session IDs

CVC session IDs are temporary. Store only:
  • ✅ Token (tok_xxx)
  • ✅ Masked card number
  • ❌ CVC session ID (temporary)
  • ❌ CVV (never store)

​
Flow Diagrams

​
Standard Payment Flow

​
Recurring Payment Flow

​
Next Steps