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 $YOUR_VAULT_URL/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

Property	Regular Token	Test Token
TTL	90 seconds	1 year (test tokens)
Deleted after use	Yes	No
Can be reused	No	Yes

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 $YOUR_VAULT_URL/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:

Tokenize with CVV
Immediately process payment
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 $YOUR_VAULT_URL/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.

Getting Started

Vault

Payments

CVC Sessions

CVC Sessions

Overview

Session Lifecycle

Creating a CVC Session

Session Properties

Using a CVC Session

Session Expiration

Regular Sessions (90 seconds)

Test Sessions (1 year)

Without CVC Session

Option 1: Skip CVV

Option 2: Re-tokenize

Error Responses

Session Not Found

Missing Session ID

Best Practices

1. Use CVC Sessions Promptly

2. Handle Expiration Gracefully

3. Use Test Tokens for Development

4. Delete a session when needed

5. Don’t Store CVC Session IDs

Flow Diagrams

Standard Payment Flow

Recurring Payment Flow

Next Steps

​CVC Sessions

​Overview

​Session Lifecycle

​Creating a CVC Session

​Session Properties

​Using a CVC Session

​Session Expiration

​Regular Sessions (90 seconds)

​Test Sessions (1 year)

​Without CVC Session

​Option 1: Skip CVV

​Option 2: Re-tokenize

​Error Responses

​Session Not Found

​Missing Session ID

​Best Practices

​1. Use CVC Sessions Promptly

​2. Handle Expiration Gracefully

​3. Use Test Tokens for Development

​4. Delete a session when needed

​5. Don’t Store CVC Session IDs

​Flow Diagrams

​Standard Payment Flow

​Recurring Payment Flow

​Next Steps

CVC Sessions

Overview

Session Lifecycle

Creating a CVC Session

Session Properties

Using a CVC Session

Session Expiration

Regular Sessions (90 seconds)

Test Sessions (1 year)

Without CVC Session

Option 1: Skip CVV

Option 2: Re-tokenize

Error Responses

Session Not Found

Missing Session ID

Best Practices

1. Use CVC Sessions Promptly

2. Handle Expiration Gracefully

3. Use Test Tokens for Development

4. Delete a session when needed

5. Don’t Store CVC Session IDs

Flow Diagrams

Standard Payment Flow

Recurring Payment Flow

Next Steps