Armazenar Cartão no Cofre

POST/v2/cards/vault

Armazena um cartão de crédito ou débito diretamente no cofre seguro, persistindo os metadados mascarados e os dados protegidos com AES-256. O identificador retornado (vaultId) pode ser utilizado em compras futuras e soluções de 1 clique (One-Click Buy).

Sem necessidade de tokenização prévia

Não é necessário tokenizar o cartão antes de chamar este endpoint. Basta passar o número do cartão diretamente no campo cardNumber. O cofre processa e gera o vaultId diretamente.

Cabeçalhos (Headers)

Cabeçalho	Tipo	Obrigatório	Descrição
`Authorization`	`string`	Sim	Token JWT Bearer (`Bearer <token>`) emitido pelo endpoint de autenticação
`Content-Type`	`string`	Sim	`application/json`

Parâmetros de Entrada (Body JSON)

Exemplo de requisição

{
  "cardNumber": "5127480000001375",
  "expiryDate": "1228",
  "customerId": "cli_98765"
}

Resposta (200 OK)

Exemplo de resposta

{
  "vaultId": "b4c2b9a7-8a3e-4d56-b0ef-6cf45217992c10a2f4d1e2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3",
  "suffix": "1375",
  "bin": "512748",
  "customerId": "cli_98765"
}

Parâmetros de Retorno

Erros

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Exemplo documentado

Falha de validação nos campos (cardNumber, expiryDate, customerId)

[
  {
    "tag": "expiryDate",
    "description": "A data de expiração informada é inválida ou já venceu."
  }
]

Observado em homologação

Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.

[
  {
    "tag": "CardNumber",
    "description": "O número do cartão é obrigatório."
  },
  {
    "tag": "ExpiryDate",
    "description": "A data de expiração do cartão é obrigatória."
  },
  {
    "tag": "CustomerId",
    "description": "O identificador do cliente pagador é obrigatório."
  }
]

Campos da resposta de erro

A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.