Anti-fraud Payment

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 Anti-fraud Payment operation lets you process transactions with higher security by using the Sopague anti-fraud library. Make sure the anti-fraud library is properly implemented in your system before using these operations. For more information, see Anti-fraud Library.

---

Perform payment operation

To create a credit card transaction, send a POST request to /v1/payments with the required data. The example below illustrates a typical request.

POST /v1/payments

Via REST request with the following body:

Request

  {
    "payment": {
      "transactionType": "string",
      "amount": 0,
      "productType": "string",
      "installments": 0
    },
    "referenceTransaction": "string",
    "urlCallBack": "string",
    "sellerInfo": {
      "codeAntiFraud": "string"
    },
    "customer": {
      "documentNumber": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phoneNumber": "string",
      "mobilePhoneNumber": "string",
      "address": "string",
      "city": "string",
      "state": "string",
      "zipCode": "string",
      "ipAddress": "string",
      "country": "string"
    },
    "cardInfo": {
      "numberToken": "string",
      "cardholderName": "string",
      "securityCode": "string",
      "brand": "string",
      "expirationMonth": "string",
      "expirationYear": "string",
      "encryptedCard": "string"
    },
    "configSplit": [
      {
        "documentNumberBeneficiary": "string",
        "percent": 0,
        "type": "string"
      }
    ]
  }

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	SIZE
Payment.TransactionType	Transaction type.	string	body	yes	fixed
Payment.Amount	Order amount (in cents).	integer	body	yes	10
Payment.ProductType	Product type – avista / lojista.	string	body	yes	fixed
Payment.Installments	Number of installments.	integer	body	yes	2
ReferenceTransaction	Payment reference provided by the integrator (returned in reconciliation).	string	body	no	50
UrlCallBack	Merchant callback URL for payment flow updates.	string	body	no	500
sellerInfo.codeAntiFraud	Code obtained via the anti-fraud library.	guid	body	yes	36
ConfigSplit	Payment split configuration list (splits the amount between multiple beneficiaries).	array	body	no	-
ConfigSplit[].documentNumberBeneficiary	Beneficiary CPF/CNPJ (numbers only, no mask).	string	body	no	14
ConfigSplit[].percent	Split percentage (0–100).	decimal	body	no	5,2
ConfigSplit[].type	Split type: bruto (gross amount) or liquido (after fees).	string	body	no	10
CardInfo.NumberToken	Tokenized card identifier.	string	body	no	fixed
CardInfo.CardholderName	Cardholder name printed on the card.	string	body	yes	30
CardInfo.SecurityCode	Security code (CVV).	string	body	no	4
CardInfo.Brand	Card brand (optional).	string	body	no	fixed
CardInfo.ExpirationMonth	Card expiration month (two digits).	string	body	no	2
CardInfo.ExpirationYear	Card expiration year (two digits).	string	body	no	2
CardInfo.EncryptedCard	Card data encrypted with the RSA public key obtained from /cards/public-key (safe alternative to sending card data in plain text).	string	body	no	2048
Customer.DocumentType	Customer document type.	string	body	no	4
Customer.DocumentNumber	Customer document number.	string	body	no	20
Customer.FirstName	Customer first name.	string	body	no	60
Customer.LastName	Customer last name.	string	body	no	60
Customer.Email	Customer email.	string	body	no	255
Customer.PhoneNumber	Customer phone number.	string	body	no	15
Customer.MobilePhoneNumber	Customer mobile phone number.	string	body	no	25
Customer.Address	Customer address.	string	body	no	60
Customer.Complement	Address complement.	string	body	no	60
Customer.City	Customer city.	string	body	no	50
Customer.State	Customer state.	string	body	no	2
Customer.ZipCode	Customer ZIP/postal code.	string	body	no	10
Customer.IpAddress	Customer device IP address.	string	body	no	48
Customer.Country	Customer country.	string	body	no	2

Note

Installment payments: for installment payments, use productType as lojista. For one-time payments (single installment), use avista.

Domains

PROPERTY	VALUES
Payment.TransactionType	credit
Payment.ProductType	avista, lojista
CardInfo.Brand	visa, mastercard, amex, elo, hipercard
Customer.DocumentType	cpf, cnpj

🟢 200

Payment completed successfully

{
  "returnCode": "0",
  "description": "Sucesso",
  "paymentId": "020080286103040952150000006201850000000000",
  "authorizationCode": "043711",
  "orderNumber": "0000000001",
  "expireAt": "2019-09-24T13:20:52.8775511-03:00",
  "amount": 1035,
  "releaseAt": "2019-09-24T13:20:52.877545-03:00"
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
ReturnCode	Return code.	string
Description	Return description.	string
PaymentId	Payment identifier (also known as TID).	string
AuthorizationCode	Authorization code.	string
OrderNumber	orderNumber provided by the client in the payment request.	string
ExpireAt	Expiration date/time for pre-authorizations.	datetime
Amount	Order amount (in cents).	integer
ReleaseAt	Payment timestamp.	datetime

🔴 400

Request error

[
  {
    "tag": "",
    "description": "O valor da venda precisa ser maior do que R$ 1,00"
  }
]

🔴 500

Internal error

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

---

See also

Response codes

To identify and properly handle error codes returned by transactions, see the full table:

Authorizer Host Response Codes →