Armazenar Cartão no Cofre

POST/v2/cards/vault

Armazena um cartão de crédito diretamente no cofre seguro, retornado um vaultId, que pode ser utilizado em compras futuras e soluções de 1 clique (One-Click Buy).

Criptografia prévia obrigatória

A criptografia prévia é obrigatória: envie o cartão criptografado em encryptCard.

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)

O valor <resultado de Sopague.encryptCard> nos exemplos JSON/cURL é ilustrativo e não pode ser enviado como um ciphertext válido. Substitua-o pelo resultado da criptografia do cartão.

Exemplo de requisição

{
  "encryptCard": "<resultado de Sopague.encryptCard>",
  "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

Os exemplos de HTTP 400 abaixo foram conferidos no código da implementação do novo contrato, não em uma nova execução em homologação. O envelope é um array de objetos com tag e description. Os exemplos históricos com o campo antigo foram removidos.

Exemplos derivados da implementação

O corpo vazio {} falha na validação dos campos obrigatórios. Embora o request use encryptCard, a tag de validação é EncryptedCard, correspondente à propriedade C#.

[
  {
    "tag": "EncryptedCard",
    "description": "O cartão criptografado é 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."
  }
]

Com expiryDate e customerId válidos, a ausência de encryptCard ou seu envio vazio/branco retorna apenas a validação EncryptedCard. As demais tags de validação são ExpiryDate e CustomerId.

Conteúdo malformado, Base64 inválido ou criptografado com a chave de outro cliente:

[
  {
    "tag": "",
    "description": "Cartão criptografado inválido."
  }
]

Os erros de serviço usam o mesmo array de objetos, com tag vazia. A tabela mostra as mensagens exatas da implementação:

Cenário	`description`
Conteúdo criptografado já utilizado	`01 - Por favor, refaça o fluxo de pagamento`
Conteúdo inválido	`02 - Parâmetros inválidos`
Payload mal formatado	`03 - Parâmetros inválidos`
Número do cartão ausente ou com menos de 12 caracteres	`04 - Parâmetros inválidos`
Sessão ausente	`05 - Parâmetros inválidos`
Sessão inválida	`06 - Parâmetros inválidos`
Sessão expirada	`07 - Sessão expirada`
Cartão inválido	`Número do cartão inválido`

Para expiração ou reutilização, refaça a criptografia e envie um novo resultado. Uma operação pode consumir o conteúdo antes de outras validações ou da criação do vault.

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.