Cofre

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Introdução

A operação de Cofre permite armazenar os dados de cartão do consumidor no cofre para uso em pagamentos futuros e recorrência. Esta funcionalidade é essencial para implementar pagamentos recorrentes e melhorar a experiência do usuário, evitando a necessidade de inserir dados do cartão a cada transação.

---

Armazenar Cartão no Cofre

Para criar um cofre a partir dos dados de cartão do consumidor, envie uma requisição POST para o endpoint /v1/vaults/cards com os dados necessários. O exemplo abaixo ilustra uma requisição típica.

POST /v1/vaults/cards

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "numberToken": "88f466c4-d17a-4430-952f-2a44bdb98525",
  "brand": "visa",
  "cardholderName": "JOSE SILVA",
  "expirationMonth": "01",
  "expirationYear": "19",
  "verifyCard": false,
  "securityCode": "123"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
NumberToken	Número do cartão tokenizado.	string	body	sim	36
Brand	Bandeira do cartão (visa, mastercard, elo, amex, hipercard).	string	body	sim	Fixo
CardholderName	Nome do comprador impresso no cartão.	string	body	sim	Segue a regra do nome contido no cartão
ExpirationMonth	Mês de expiração do cartão com dois dígitos.	string	body	sim	2
ExpirationYear	Ano de expiração do cartão com dois dígitos.	string	body	sim	2
VerifyCard	Realiza uma transação que verifica se o cartão informado é válido.	boolean	body	sim	Fixo
SecurityCode	Código de segurança.	string	body	não	04

Observação

O parâmetro verifyCard quando definido como true realizará uma transação de verificação para validar se o cartão informado é válido. Esta operação pode gerar uma pequena cobrança dependendo da bandeira do cartão.

Domínios

PROPRIEDADE	CONTEÚDO
Brand	visa, mastercard, elo, amex, hipercard

🟢 200

Cartão armazenado com sucesso

{
  "vaultId": "90fa2d95-3430-4e32-b86b-5b3b3a8393cb"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
VaultId	Identificador do cartão salvo no cofre.	string

🔴 400

Erro na requisição

[
  {
    "tag": "",
    "description": "Dados do cartão inválidos"
  }
]

🔴 500

Erro interno

[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]