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 /v2/cards/vault com os dados necessários. O exemplo abaixo ilustra uma requisição típica.

POST /v2/cards/vault

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

Requisição

{
  "cardNumber": "string",
  "expiryDate": "string",
  "customerId": "string"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
cardNumber	Número do cartão tokenizado.	string	body	sim	19
expiryDate	Data de expiração do cartão.	string	body	sim	4
customerId	Identificador do cartão tokenizado.	string	body	sim	13

🟢 200

Cartão armazenado com sucesso

{
  "vaultId": "string",
  "bin": "string",
  "sufix": "string",
  "customerId": "string"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
vaultId	Cartão tokenizado.	string
bin	6 primeiros dígitos do cartão.	string
sufix	4 últimos dígitos do cartão.	string
customerId	Id do cartão customizado.	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."
  }
]

---

Consultar Tokens do Cofre

Para consultar os tokens de cartão armazenados no cofre de um consumidor, envie uma requisição GET para o endpoint /v2/cards/vault informando o customerId. Também é possível utilizar os parâmetros skip e take para paginação.

GET /v2/cards/vault?customerId={customerId}&skip={skip}&take={take}

Via request Representational State Transfer (REST) com query parameters:

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO
customerId	Identificador do consumidor vinculado aos tokens.	string	query params	sim
skip	Quantidade de registros a ignorar na consulta.	int	query params	não
take	Quantidade de registros a retornar na consulta.	int	query params	não

🟢 200

Tokens consultados com sucesso

{
  "items": [],
  "totalCount": 0,
  "skip": 0,
  "take": 10
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
items	Lista de tokens encontrados para o consumidor.	array
totalCount	Quantidade total de registros encontrados.	int
skip	Quantidade de registros ignorados na consulta.	int
take	Quantidade de registros retornados por página.	int

🔴 400

Erro na requisição

[
  {
    "tag": "",
    "description": "Dados da consulta inválidos"
  }
]

🔴 500

Erro interno

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

---

Ativar ou Desativar Token do Cofre

Para ativar ou inativar um token de cartão armazenado no cofre, envie uma requisição POST para o endpoint /v2/cards/vault/status informando o vaultId e o novo status desejado.

POST /v2/cards/vault/status

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

Requisição

{
  "vaultId": "string",
  "active": true
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO
vaultId	Token do cartão a ser ativado ou desativado.	string	body	sim
active	Envie true para ativar o token ou false para inativar o token.	boolean	body	sim

🟢 200

Status do token alterado com sucesso

{
  "vaultId": "string",
  "status": "string"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
vaultId	Token do cartão alterado.	string
status	Novo status do token.	string

🔴 400

Token não localizado ou inativo

[
  {
    "tag": "",
    "description": "VaultId não localizado ou inativo para a conta autenticada."
  }
]

🔴 500

Erro interno

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

Observação

Ao inativar um token, ao tentar realizar um pagamento será recebido o erro HTTP Status Code 400 com a mensagem: "VaultId não localizado ou inativo para a conta autenticada.".