Pular para o conteúdo principal
GET
/
credit-card
/
v1
/
payment
/
token
/
{buyerUuid}
Obter Tokens de Cartão por Comprador
curl --request GET \
  --url https://api-gateway.firebanking.dev/credit-card/v1/payment/token/{buyerUuid} \
  --header 'x-api-key: <api-key>'
[
  {
    "cardToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "maskedCardNumber": "****-****-****-1111",
    "expirationDate": "12/24",
    "createdAt": "2023-11-07T05:31:56Z"
  }
]
Recuperar todos os tokens de cartão salvos para um comprador específico. Isso é útil para exibir métodos de pagamento salvos aos clientes durante o checkout.

​
Parâmetros de Caminho

​
buyerUuid
string
required
O UUID do comprador cujos tokens de cartão você deseja recuperar

​
Exemplo de Requisição

cURL
curl -X GET "https://api-gateway.firebanking.com.br/credit-card/v1/payment/token/buyer-uuid-12345" \
  -H "x-api-key: SUA_CHAVE_DE_API"

​
Exemplo de Resposta

Resposta
[
  {
    "cardToken": "550e8400-e29b-41d4-a716-446655440000",
    "maskedCardNumber": "****-****-****-4444",
    "expirationDate": "06/26",
    "cardBrand": "mastercard",
    "cardType": "credit",
    "isExpired": false,
    "createdAt": "2024-01-15T14:30:00Z",
    "lastUsedAt": "2024-01-20T10:15:00Z"
  },
  {
    "cardToken": "660f9500-f39c-52e5-b827-557766551111",
    "maskedCardNumber": "****-****-****-1111",
    "expirationDate": "12/25",
    "cardBrand": "visa",
    "cardType": "credit",
    "isExpired": false,
    "createdAt": "2024-01-10T09:20:00Z",
    "lastUsedAt": "2024-01-18T16:45:00Z"
  }
]

​
Campos da Resposta

​
cardToken
string
Identificador único do token para o cartão salvo
​
maskedCardNumber
string
Número do cartão mascarado para fins de exibição
​
expirationDate
string
Data de expiração do cartão no formato MM/AA
​
cardBrand
string
Bandeira do cartão (visa, mastercard, american_express, etc.)
​
cardType
string
Tipo de cartão (credit, debit, prepaid)
​
isExpired
boolean
Se o cartão expirou
​
lastUsedAt
string
Timestamp de quando o token foi usado pela última vez para um pagamento

​
Lidando com Cartões Expirados

Tokens expirados ainda são retornados na resposta mas marcados com isExpired: true. Você deve:
  1. Ocultar da UI - Não mostrar cartões expirados na seleção de pagamento
  2. Solicitar atualização - Pedir aos clientes para atualizar cartões expirados
  3. Limpeza - Considerar remover tokens expirados muito antigos

​
Resposta Vazia

Se um comprador não tem cartões salvos, o endpoint retorna um array vazio:
Resposta Vazia
[]

​
Casos de Uso

Exibição no Checkout

Mostrar métodos de pagamento salvos durante o checkout

Gerenciamento de Conta

Permitir que clientes gerenciem seus cartões salvos

Configuração de Assinatura

Exibir cartões para pagamentos de assinatura

Recompra Rápida

Habilitar compra com um clique
Ordene tokens por lastUsedAt para mostrar os cartões usados mais recentemente primeiro em sua UI.

​
Cenários de Erro

  • Comprador não encontrado: O UUID do comprador não existe
  • Sem tokens: Comprador não tem tokens de cartão salvos (retorna array vazio)
  • UUID inválido: O formato do UUID do comprador é inválido

​
Considerações de Segurança

  • Nunca armazene o número completo do cartão desta resposta
  • Sempre exija CVV ao usar tokens para pagamentos
  • Implemente controles de acesso adequados para garantir que usuários vejam apenas seus próprios tokens

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Path Parameters

​
buyerUuid
string<uuid>
required

UUID do comprador

Response

200 - application/json

Tokens de cartão recuperados com sucesso

​
cardToken
string<uuid>

Token do cartão gerado

​
maskedCardNumber
string

Número do cartão mascarado

Example:

"****-****-****-1111"

​
expirationDate
string

Data de expiração do cartão

Example:

"12/24"

​
createdAt
string<date-time>

Timestamp de criação do token