flowglad/pay-skills/card-sessions

Card Sessions

Abstract

Card sessions are the secure mechanism for accessing virtual card details (number, CVV, expiry) in Flowglad Pay. A session is created against a payment method, which returns a short-lived scoped JWT token. That token is then used to redeem the session and retrieve card details. This two-step flow ensures card details never leak into MCP tool contexts or long-lived API key scopes.

Table of Contents

1. Security Model — CRITICAL
2. Create a Card Session — CRITICAL
3. Redeem a Card Session — CRITICAL
4. Check Session Status — MEDIUM
5. Audit Redemptions — MEDIUM
6. Session Lifecycle — LOW

1. Security Model

Impact: CRITICAL — misunderstanding this causes auth failures

Card details are never returned by:

• Standard API key authenticated endpoints
• MCP tools (intentionally omitted from AI context windows)

Instead, card details require a scoped redeem token — a short-lived HS256 JWT with:

• scope: card-session:redeem:{paymentMethodId}
• sub: user ID
• Expiry matching the session TTL

The token is returned when creating a session and must be passed via the X-Scoped-Token header when redeeming.

2. Create a Card Session

Creates a session and returns a scoped redeem token.

REST API

POST /v1/card-sessions
Header: X-API-Key: <api-key>
Content-Type: application/json

Request body:

{
  "paymentMethodId": "pm_abc123",
  "ttlSeconds": 300,
  "maxRedeemCount": 1
}

Response (200):

{
  "session": {
    "id": "cs_xyz789",
    "userId": "usr_abc",
    "paymentMethodId": "pm_abc123",
    "status": "active",
    "maxRedeemCount": 1,
    "redeemCount": 0,
    "expiresAt": "2026-03-11T12:05:00.000Z",
    "createdAt": "2026-03-11T12:00:00.000Z",
    "updatedAt": "2026-03-11T12:00:00.000Z"
  },
  "redeemToken": "eyJhbGciOiJIUzI1NiIs..."
}

CLI

fgp card-sessions create <payment-method-id> [--ttl 300] [--max-redemptions 1] [--json]

MCP Tool

create_card_session(paymentMethodId, ttlSeconds?, maxRedeemCount?)

Important: The MCP tool returns session metadata and a hint, but does NOT return card details. You must use the REST API redeem endpoint with the scoped token.

3. Redeem a Card Session

Exchanges a scoped token for card details. This is the only way to get card PAN/CVV/expiry.

REST API

POST /v1/card-sessions/{id}/redeem
Header: X-Scoped-Token: <redeem-token>
Content-Type: application/json

No request body required. Authentication is via the scoped token only (not the API key).

Response (200):

{
  "number": "4242424242424242",
  "expMonth": 12,
  "expYear": 2027,
  "cvc": "123"
}

CLI

fgp card-sessions redeem <session-id> --token <redeem-token> [--json]

Shortcut: Create + Redeem in One Step

The fgp card command creates a session and immediately redeems it:

fgp card [--payment-method-id pm_abc123] [--json]

If using an agent-scoped API key, this automatically resolves the agent's payment method ID.

Error Responses

4. Check Session Status

REST API

GET /v1/card-sessions/{id}
Header: X-API-Key: <api-key>

Response: Same session object as create (without redeemToken).

CLI

fgp card-sessions get <session-id> [--json]

MCP Tool

get_card_session(id)

5. Audit Redemptions

List all redemption records for a session, including IP addresses and timestamps.

REST API

GET /v1/card-sessions/{id}/redemptions
Header: X-API-Key: <api-key>

Response:

{
  "redemptions": [
    {
      "id": "csr_abc",
      "cardSessionId": "cs_xyz789",
      "ipAddress": "203.0.113.42",
      "redeemedAt": "2026-03-11T12:01:30.000Z"
    }
  ]
}

CLI

fgp card-sessions redemptions <session-id> [--json]

MCP Tool

get_card_session_redemptions(id)

6. Session Lifecycle

Sessions progress through these statuses:

active → redeemed    (after maxRedeemCount reached)
active → expired     (after TTL elapses)
redeemed → scrubbed  (vault reference destroyed, card details permanently removed)
expired → scrubbed

• active: Can be redeemed (redeemCount < maxRedeemCount, not past expiresAt)
• redeemed: All redemptions used, card details still in vault temporarily
• expired: TTL elapsed, no further redemptions possible
• scrubbed: Card details permanently purged from vault