Métodos de pagamento do Customer Portal

Estes endpoints permitem que um cliente autenticado gerencie os próprios métodos de pagamento: listar instrumentos salvos, adicionar um novo e remover um. Adicionar um cartão usa a mesma tokenização no navegador do checkout — os dados do cartão são criptografados em iframes isolados e nunca chegam aos seus servidores nem à Tokeflow em texto claro.

O que o cliente vê é o resumo não sensível — bandeira, últimos quatro dígitos, validade — nunca o cartão completo. A remoção de um instrumento contra o qual uma assinatura ainda cobra é protegida, para que uma renovação não fique órfã.

O objeto do método de pagamento

Retornado pelos endpoints de listagem e consulta desta página.

Endpoints

GET/api/v1/portal/payment-methods

Lista os cartões salvos.

Exemplo de requisição

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

Exemplo de resposta — 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

Cadastra um novo cartão.

Campos da requisição

Exemplo de requisição

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"
  }'

Exemplo de resposta — 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 um cartão salvo.

Parâmetros de caminho

Exemplo de requisição

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

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

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

Define um cartão como padrão da carteira.

Parâmetros de caminho

Exemplo de requisição

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

Exemplo de resposta — 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

Inicia uma sessão de tokenização (credenciais de criptografia).

Exemplo de requisição

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

Exemplo de resposta — 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

Registra um cartão criptografado.

Campos da requisição

Exemplo de requisição

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"
    }
  }'

Exemplo de resposta — 201

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

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

Relacionados

• Assinaturas do portal
• Tokenização
• Instrumentos de pagamento (API pública)