Customer Portal payment methods

These endpoints let a signed-in customer manage their own payment methods: list saved instruments, add a new one, and remove one. Adding a card uses the same in-browser tokenization as checkout — card data is encrypted in isolated iframes and never reaches your servers or Tokeflow in the clear.

What the customer sees is the non-sensitive summary — brand, last four, expiry — never the full card. Removing an instrument that a subscription still bills against is guarded so a renewal is not orphaned.

The payment method object

Returned by the list and retrieve endpoints on this page.

Endpoints

GET/api/v1/portal/payment-methods

List cards on file.

Example request

curl https://api.tokeflow.com/api/v1/portal/payment-methods \
  -H "Cookie: tf_portal_session=…"

Example response — 200

{
  "data": [
    {
      "id": "pi_123",
      "instrument_type": "card",
      "card_brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027,
      "is_default": true,
      "status": "active"
    }
  ]
}

POST/api/v1/portal/payment-methods

Enroll a new card on file.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/payment-methods \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "card_ciphertext_id": "tok_8f3c2a1b9d4e"
  }'

Example response — 201

{
  "id": "pi_123",
  "instrument_type": "card",
  "card_brand": "visa",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2027,
  "is_default": true,
  "status": "active"
}

DELETE/api/v1/portal/payment-methods/:id

Remove a card on file.

Path parameters

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/portal/payment-methods/obj_1a2b3c4d \
  -H "Cookie: tf_portal_session=…"

Example response — 204 No Content

An empty body is returned on success.

POST/api/v1/portal/payment-methods/:id/set-default

Set a card as the wallet default.

Path parameters

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/payment-methods/obj_1a2b3c4d/set-default \
  -H "Cookie: tf_portal_session=…"

Example response — 200

{
  "id": "pi_123",
  "instrument_type": "card",
  "card_brand": "visa",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2027,
  "is_default": true,
  "status": "active"
}

POST/api/v1/portal/tokenization/session

Start a tokenization session (encryption credentials).

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/tokenization/session \
  -H "Cookie: tf_portal_session=…"

Example response — 201

{
  "session_id": "sess_...",
  "sdk": {
    "js_url": "https://vault.tokeflow.com/v2",
    "sri_expires_at": 1
  },
  "expires_at": "2026-01-15T12:30:00.000Z"
}

POST/api/v1/portal/tokenization/tokens

Register an encrypted card.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/portal/tokenization/tokens \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_...",
    "encryptedCard": {
      "number": "ev:QkTC:q6/SoVBehipxsy6j:...",
      "cvc": "ev:QkTC:JfW5fyt5eOb2vXAX:...",
      "expiryMonth": "12",
      "expiryYear": "25",
      "name": "ev:QkTC:..."
    },
    "metadata": {
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "bin": "424242"
    }
  }'

Example response — 201

{
  "token_id": "tok_8f3c2a1b9d4e",
  "brand": "visa",
  "last4": "4242",
  "exp_month": "12",
  "exp_year": "2027"
}

Errors

Errors use the standard envelope. The most common cases here:

Related

• Portal subscriptions
• Tokenization
• Payment instruments (public API)