POST/v1/cards/:id/reveal

Reveal card details

Returns the full card number and CVV for a brief, one-time window.

Required scope: cards.readRate limit: 10 rps

Requires a valid X-2FA-Code header (a 6-digit TOTP code) in addition to the API key — the same step-up gate the dashboard's own reveal flow uses. Every failure mode (missing header, 2FA not enrolled, wrong code) collapses to one 403 step_up_required response, to avoid leaking whether 2FA is enrolled.

Parameters

idstringrequired

The card ID.

X-2FA-Codestringrequired

A current 6-digit TOTP code from the user's enrolled authenticator app.

Code samples

curl -X POST "https://samaprime.com/api/v1/cards/smsord_01J8X9AABBCCDD/reveal" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json"
  -H "X-2FA-Code: 123456"

Response

→ 200
{
  "data": {
    "pan": "4111 •••• •••• 1234",
    "cvv": "•••"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
403	`step_up_required` The X-2FA-Code header was missing, invalid, or 2FA isn't enrolled for this account.
404	`not_found` No card with this ID belongs to this user.
409	`not_issued` The card hasn't finished issuing yet — there are no details to reveal.