Consultar e Listar

Consultar cartão por token

GET /api/v1/cards/{tokenCard}

Retorna os dados de um cartão tokenizado a partir do seu token.

Requer autenticação mTLS. Veja Autenticação.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Exemplo
`tokenCard`	string	sim	`a1b2c3d4-e5f6-4789-9abc-def012345678`

`200 OK`

{
  "codigoResposta": "0",
  "mensagemResposta": "Consulta realizada com sucesso",
  "cartoes": [
    {
      "statusCard": "ATV",
      "bandeiraCartao": "1",
      "token": "a1b2c3d4-e5f6-4789-9abc-def012345678",
      "bin": "411111",
      "suffix": "1111",
      "dataExpiracao": "12/28",
      "customerId": "CLI-000123",
      "dataCriacao": "2026-08-01T14:30:00",
      "dataModificacao": "2026-08-01T14:30:00"
    }
  ],
  "paginaAtual": "1",
  "totalPaginas": "1",
  "quantidade": "1"
}

Campos da resposta

Campo	Tipo	Descrição
`codigoResposta`	string	Código de resposta da consulta
`mensagemResposta`	string	Mensagem de resposta da consulta
`cartoes`	array	Lista de cartões encontrados (objeto `Cartão`)
`paginaAtual`	string	Página atual do resultado
`totalPaginas`	string	Total de páginas
`quantidade`	string	Quantidade de cartões retornados

Campos de `cartoes[]`

Campo	Tipo	Descrição
`statusCard`	enum	`ATV` ativo, `INA` inativo
`bandeiraCartao`	string	Código da bandeira
`token`	string	Token do cartão
`bin`	string	BIN do cartão
`suffix`	string	Últimos 4 dígitos
`dataExpiracao`	string	Validade `MM/AA`
`customerId`	string	Identificador do cliente
`dataCriacao`	string	Data de criação
`dataModificacao`	string	Data da última modificação

Erros: 404 cartão não encontrado · 500 erro interno.

Buscar cartão por ID

GET /api/v1/cards/id/{id}

Retorna os dados de um cartão a partir do seu identificador único (UUID).

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Exemplo
`id`	string (uuid)	sim	`8f14e45f-ceea-467e-9a9f-1d1a3c1e5b3a`

`200 OK`

{
  "code": "0",
  "message": "Cartão encontrado",
  "token": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "suffix": "1111",
  "bin": "411111",
  "statusTransaction": "CON",
  "nsua": "123456789012345",
  "nita": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "merchantUsn": "123456789012",
  "clientId": "CLI-000123",
  "bandeiraCartao": "1"
}

Campos da resposta

Campo	Tipo	Descrição
`code`	string	Código de resposta. Diferente de `0` significa falha (max 4)
`message`	string	Mensagem de resposta (max 500)
`token`	string	Token que representa o cartão
`suffix`	string	Últimos 4 dígitos do cartão
`bin`	string	BIN do cartão — identifica emissor e bandeira (max 8)
`statusTransaction`	enum	Status da tokenização — ver Status de transação
`nsua`	string	NSU da adquirente para a transação de tokenização (max 15)
`nita`	string	NIT da adquirente — identificador da transação de tokenização (max 64)
`merchantUsn`	string	Número sequencial único enviado pela loja na tokenização (max 12)
`clientId`	string	Identificador do cliente/lojista
`bandeiraCartao`	string	Código da bandeira do cartão

Erros: 401 não autorizado · 404 cartão não encontrado · 500 erro interno.

Listar cartões

GET /api/v1/cards

Retorna uma lista paginada de todos os cartões cadastrados.

Query params

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`page`	integer	não	`0`	Página desejada, começando em `0`
`size`	integer	não	`20`	Quantidade de itens por página (mínimo `1`)
`sort`	array	não	`dataCriacao,desc`	Campo e direção de ordenação; pode repetir

`200 OK`

{
  "content": [
    {
      "statusCard": "ATV",
      "bandeiraCartao": "1",
      "token": "a1b2c3d4-e5f6-4789-9abc-def012345678",
      "bin": "411111",
      "suffix": "1111",
      "dataExpiracao": "12/28",
      "customerId": "CLI-000123",
      "dataCriacao": "2026-08-01T14:30:00",
      "dataModificacao": "2026-08-01T14:30:00"
    }
  ],
  "number": 0,
  "size": 20,
  "numberOfElements": 1,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true,
  "empty": false
}

Campos da paginação

Campo	Tipo	Descrição
`content`	array	Cartões da página atual
`number`	integer	Índice da página atual (base `0`)
`size`	integer	Tamanho da página solicitado
`numberOfElements`	integer	Quantidade de itens na página atual
`totalElements`	integer	Total de cartões encontrados
`totalPages`	integer	Total de páginas
`first` / `last`	boolean	Indicam se é a primeira / última página
`empty`	boolean	Indica se a página não possui itens

Erros: 401 não autorizado · 500 erro interno.

Consultar e Listar

On this page