flowglad 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
- Security Model — CRITICAL
- Create a Card Session — CRITICAL
- Redeem a Card Session — CRITICAL
- Check Session Status — MEDIUM
- Audit Redemptions — MEDIUM
- 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
}
| Field | Type | Required | Default | Validation |
|---|---|---|---|---|
paymentMethodId |
string | Yes | — | Must start with pm_ |
ttlSeconds |
integer | No | 300 | 30–3600 |
maxRedeemCount |
integer | No | 1 | 1–10 |
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
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED |
Missing or invalid scoped token |
| 403 | FORBIDDEN |
Token scope doesn't match session's payment method |
| 404 | NOT_FOUND |
Session not found |
| 409 | CONFLICT |
Session expired, exhausted, or invalid status |
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