Card Vault

API data

API Gateway
This API is used for payment gateway operations:

• Production: https://api.sopague.com.br/gateway
• Sandbox: https://api-hmg.sopague.com.br/gateway
• Architecture: Representational State Transfer (REST)

Introduction

The Vault operation lets you store a consumer’s card data in the vault for future payments and recurrence. This functionality is essential to implement recurring payments and improve the user experience by avoiding the need to enter card data on every transaction.

---

Store card in the vault

To create a vault record from a consumer’s card data, send a POST request to /v1/vaults/cards with the required data. The example below shows a typical request.

POST /v1/vaults/cards

Via REST request with the following body:

Request

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

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
NumberToken	Tokenized card number.	string	body	yes	36
Brand	Card brand (visa, mastercard, elo, amex, hipercard).	string	body	yes	Fixed
CardholderName	Cardholder name printed on the card.	string	body	yes	Must match the name on the card
ExpirationMonth	Card expiration month (two digits).	string	body	yes	2
ExpirationYear	Card expiration year (two digits).	string	body	yes	2
VerifyCard	Performs a verification transaction to check whether the provided card is valid.	boolean	body	yes	Fixed
SecurityCode	Security code (CVV).	string	body	no	04

Note

When verifyCard is set to true, the system performs a verification transaction to validate the card. This operation may generate a small charge depending on the card brand.

Domains

PROPERTY	VALUES
Brand	visa, mastercard, elo, amex, hipercard

🟢 200

Card stored successfully

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

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
VaultId	Identifier of the card stored in the vault.	string

🔴 400

Request error

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

🔴 500

Internal error

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