Viewing card details (PAN / CVV)

GET /v1/cards and GET /v1/cards/{id} never return full PAN or CVV. They only include safe fields such as lastFour, status, and expiry label. To show the full number, expiry, and CVV you use one of the two reveal methods below. Pick based on whether sensitive data may touch your servers.

Which method should I use?

	Method 1 — Widget (default)	Method 2 — Server-side (PCI)
Who	Most tenants	Orgs with PCI DSS Level 1 (Apocor enables `pciRevealEnabled`)
Where PAN/CVV live	PCI iframes in the browser	Your PCI-scoped backend after decrypt
API	`GET /v1/cards/{id}/secure-details`	`POST /v1/cards/{id}/payment-details`
SDK / crypto	Apocor Widget.js + `widget.bootstrap`	RSA-OAEP + AES-256-GCM envelope
PCI burden	Low (display only)	High (you handle card data)

If you only need to display card details in a web or mobile WebView UI, use Method 1. Use Method 2 only when your backend must process PAN/CVV and you have PCI DSS Level 1 attestation.

API Reference endpoints for both methods live under Cards — reveal PAN/CVV.

Your servers receive a short-lived revealToken only. The browser loads Apocor Widget.js; PAN/CVV render inside PCI iframes and never pass through your backend.

Steps

Authenticate → Bearer token (Authentication).
Call GET /v1/cards/{id}/secure-details.
Load the Apocor Widget SDK (sandbox vs live must match the token environment).
Call widget.bootstrap({ clientAccessToken: revealToken, ... }).
Ask Apocor to allowlist your page origin (the domain of your app, not api.apocor.ai).

Get a reveal token

cURL

curl -s 'https://api.apocor.ai/v1/cards/card_abc123/secure-details' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{ "data": { "revealToken": "rvl_9f8e...", "expiresIn": 300 } }

Environment	Script URL
Sandbox / TEST	`https://api.apocor.ai/sdk/card/sandbox/1.0.0/index.min.js`
Live	`https://api.apocor.ai/sdk/card/1.0.0/index.min.js`

Optional CDN (same paths): https://static.apocor.ai/sdk/card/... Reference (API Reference → Cards — reveal PAN/CVV): GET …/secure-details · Widget.js sandbox · Widget.js live.

Frontend example

<div id="card-pan"></div>
<div id="card-exp"></div>
<div id="card-cvv"></div>

<script src="https://api.apocor.ai/sdk/card/sandbox/1.0.0/index.min.js"></script>
<script>
  widget.bootstrap({
    clientAccessToken: "REVEAL_TOKEN_FROM_SECURE_DETAILS",
    component: {
      showPan: {
        cardPan: { domId: "card-pan", format: true },
        cardExp: { domId: "card-exp", format: true },
        cardCvv: { domId: "card-cvv" },
      },
    },
    callbackEvents: {
      onSuccess: () => console.log("card fields ready"),
      onFailure: (err) => console.error(err),
    },
  });
</script>

A revealToken expires in about 5 minutes and is single-purpose. Never log it. Match Sandbox SDK with TEST tokens and Live SDK with LIVE tokens.

Method 2 — Server-side encrypted reveal (PCI DSS Level 1)

Apocor never returns plaintext PAN/CVV over HTTP. You send an RSA public key; we return a hybrid encrypted envelope. Decrypt only inside a PCI-scoped environment (HSM/KMS for the private key). Requires: pciRevealEnabled = true on your organization (ask Apocor after PCI attestation). Algorithm: RSA_OAEP_SHA256_AES_256_GCM

Steps

Generate an RSA-2048+ key pair; keep the private key in HSM/KMS.
POST /v1/cards/{id}/payment-details with encryption.public_key_pem.
Unwrap encryptedKey with RSA-OAEP (SHA-256).
Decrypt ciphertext with AES-256-GCM using iv + authTag.

Reference: POST …/payment-details.

Request

cURL

curl -s -X POST 'https://api.apocor.ai/v1/cards/card_abc123/payment-details' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "encryption": {
      "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
    }
  }'

Response envelope

{
  "data": {
    "algorithm": "RSA_OAEP_SHA256_AES_256_GCM",
    "encryptedKey": "<base64>",
    "iv": "<base64>",
    "authTag": "<base64>",
    "ciphertext": "<base64>",
    "expiresIn": 120
  }
}

Decrypted payload

{
  "pan": "411111…",
  "cvv": "123",
  "expMonth": "12",
  "expYear": "29",
  "bin": "49387519",
  "lastFour": "0063",
  "cardId": "card_abc123"
}

Node.js decrypt example

import crypto from "node:crypto";

function decryptPaymentDetails(privateKeyPem, envelope) {
  const aesKey = crypto.privateDecrypt(
    {
      key: privateKeyPem,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: "sha256",
    },
    Buffer.from(envelope.encryptedKey, "base64"),
  );
  const decipher = crypto.createDecipheriv(
    "aes-256-gcm",
    aesKey,
    Buffer.from(envelope.iv, "base64"),
  );
  decipher.setAuthTag(Buffer.from(envelope.authTag, "base64"));
  const json = Buffer.concat([
    decipher.update(Buffer.from(envelope.ciphertext, "base64")),
    decipher.final(),
  ]).toString("utf8");
  return JSON.parse(json);
}

Call payment-details only from a PCI-scoped service. Never log PAN/CVV or the private key. Never send the private key to Apocor. If you are not PCI Level 1, use Method 1 instead (403 if pciRevealEnabled is false).

Endpoint	Method
`GET /v1/cards/{id}/secure-details`	Method 1 token
`GET /sdk/card/sandbox/1.0.0/index.min.js`	Method 1 SDK (TEST)
`GET /sdk/card/1.0.0/index.min.js`	Method 1 SDK (live)
`POST /v1/cards/{id}/payment-details`	Method 2 envelope

Get started

Core concepts

Webhooks & events

Reference

Viewing card details (PAN / CVV)

Which method should I use?

Method 1 — Widget.js (recommended)

Steps

Get a reveal token

Widget SDK URLs

Frontend example

Method 2 — Server-side encrypted reveal (PCI DSS Level 1)

Steps

Request

Response envelope

Decrypted payload

Node.js decrypt example

​Which method should I use?

​Method 1 — Widget.js (recommended)

​Steps

​Get a reveal token

​Widget SDK URLs

​Frontend example

​Method 2 — Server-side encrypted reveal (PCI DSS Level 1)

​Steps

​Request

​Response envelope

​Decrypted payload

​Node.js decrypt example

​Related API Reference

Which method should I use?

Method 1 — Widget.js (recommended)

Steps

Get a reveal token

Widget SDK URLs

Frontend example

Method 2 — Server-side encrypted reveal (PCI DSS Level 1)

Steps

Request

Response envelope

Decrypted payload

Node.js decrypt example

Related API Reference