POST Integration/`{integrationId}`

The /Integration/integrationId route allows integrating specific transaction information identified by the integrationId.

It receives detailed transaction data, such as values, devices, billing and shipping information, as well as items and payments. After processing, the route returns an analysis with results, including decisions, biometric verifications, and insights. Authentication with a security token is required to use it.

Endpoint Authentication

The endpoint requires authentication. Clients must provide valid credentials so the system can successfully authenticate and transmit data.

Supported Authentication Method: Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

📘
Details about the authentication process and how to obtain a token can be found in Authentication.

Integration Identification by Module

Each system module has a specific integrationId that uniquely identifies it, these are:

Module	Type
Decision	Synchronous
Score	Synchronous
MFA	Asynchronous
Biolink	Asynchronous
Insights	Synchronous

Note: It is possible to compose multiple modules, which provides greater flexibility and granularity in the integration between functionalities, allowing to efficiently address more complex scenarios.

Synchronous and Asynchronous Modules

Synchronous Module Operation

Synchronous modules perform data analysis immediately upon receiving a request. This process involves cross-referencing multiple relevant pieces of information to calculate the score and determine the request status.

The analysis response is returned within seconds, allowing for quick decisions integrated into the application flow, without the need for asynchronous processing or prolonged waiting.

Asynchronous Module Operation

Asynchronous modules process requests non-immediately, allowing data analysis to occur in the background after the request is received. During this process, various relevant pieces of information are cross-referenced for score calculation and request status definition.

Upon completion of processing, the system performs an automatic notification via webhook, sending the results to the endpoint previously provided by the client.

📘
Our services address:
Homologation:
POST https://homologapix.clearsale.com.br/connect/v1/integration/integrationId
Production:
POST https://apix.clearsale.com.br/connect/v1/integration/integrationId

Configuration for Staging Environment

The staging environment is used for integration testing between systems. By default, responses are generated with fixed values, but it is possible to request custom configurations in the modules that offer this option.

The definition of the score and status is based on the last digit of the numeric field present in the billing document, allowing different scenarios to be simulated in a controlled manner.

Available Modules

Decision (standard and customized)
Score (standard and customized)
MFA (standard)
Biolink (standard and customized)
Insights (standard)

Default Score Configuration

Document (last digit)	Score Range (randomly generated)
0	0.0000 – 0.1000
1	0.1001 – 0.2000
2	0.2001 – 0.3000
3	0.3001 – 0.4000
4	0.4001 – 0.5000
5	0.5001 – 0.6000
6	0.6001 – 0.7000
7	0.7001 – 0.8000
8	0.8001 – 0.9000
9	0.9001 – 0.9999

Default Status Configuration

Document (last digit)	Status
0	APA – Automatic Approval
1	RPA – Automatic Rejection
2	AMA – Queued
3	FRD – Confirmed Fraud
4	APM – Approved
5	APP – Approved by Policy
6	AME – External Manual Review
7	APB – Approved by Biometrics
8	APS - Approved by SMS
9	ACT - Approved by Contingency

Webhook Configuration

For the MFA and Biolink modules, it is possible to configure a webhook to receive notifications or results directly at an endpoint defined by the client.

This feature allows:

Real-time integration with internal systems.
Automation of processes based on returned events.
Greater control over tests and responses in the staging environment.

To enable the webhook, provide:

The endpoint URL that will receive the requests.
Expected format: JSON.
Authentication, if required (Basic, ApiKey, JWT).

Schema Request

This section represents the general request structure for integration. The requirement of certain fields may vary depending on the context, and these specific rules will be detailed in the documentation for each individual module.

Description	Fields	Type	Required
Transaction information	transaction	Transaction	Yes
Transaction value information	transactionValue	Transaction Value	No
Device information	device	Device	No
Billing information	billing	Billing	Yes
Shipping information	shipping	Shipping	No
List of transaction items	items	Item Array	No
List of payment methods	payments	Payment Array	No
Air travel information	airTravel	Air Travel	No
Payment link information	paymentLink	PaymentLink	No
Seller information	seller	Seller	No

Transaction

Represents transaction data.

Fields	Description	Type	Length	Required
code	Unique transaction code	String	50	Yes
date	Transaction date	DateTime	-	Yes
email	Email associated with the transaction	String	150	No
status	Transaction status	Integer	-	No
ipAddress	Customer IP address	String	150	No
origin	Transaction origin: APP, WEBSITE, TELEVENDAS, etc	String	150	No
observation	Additional observations	String	8000	No

Transaction Value

Represents the total transaction value.

Fields	Description	Type	Required
totalValue	Total transaction value	Float	Yes

Device

Represents information about the device used in the transaction.

Fields	Description	Type	Required
fingerprint	Unique device identifier	Fingerprint	Yes

Fingerprint

Represents identification information of the device used in the transaction.

Fields	Description	Type	Required
sessionId	Unique device session identifier	Guid	Yes

Billing

Represents billing information.

Fields	Description	Type	Length	Required
type	Person type	Integer	-	No
name	Customer name	String	500	Yes
email	Customer email	String	150	No
gender	Customer gender	String	1	No
birthdate	Customer birthdate	DateTime	-	No
documents	Customer documents	Document Array	-	Yes
address	Billing address	Address	-	No
phones	Customer phones	Phone Array	-	Yes

Shipping

Represents shipping information.

Fields	Description	Type	Length	Required
type	Person type	Integer	-	No
price	Shipping price	Float	-	No
name	Recipient name	String	500	Yes
email	Recipient email	String	150	No
gender	Recipient gender	String	1	No
birthdate	Recipient birthdate	DateTime	-	No
clientId	Internal customer identifier (who made the transaction)	String	200	No
deliveryType	Delivery type	Integer	-	Yes
deliveryTime	Estimated delivery time	String	100	No
documents	Recipient documents	Document Array	-	No
address	Shipping address	Address	-	No
phones	Associated phones	Phone Array	-	No

Item

Represents a transaction item.

Fields	Description	Type	Length	Required
code	Internal customer item code	String	50	No
name	Item name	String	150	No
description	Item description	String	500	No
categoryId	Internal customer item category ID	Integer	-	No
categoryName	Item category name (example table in Glossary)	String	200	No
barCode	Item barcode	String	30	No
value	Item value	Float	-	Yes
quantity	Item quantity	Integer	-	Yes
isGift	Indicates if the item is a gift	Boolean	-	No
sellerName	Seller name	String	150	No
sellerSegment	Seller segment	String	150	No
isMarketPlace	Indicates if it is a marketplace	String	50	No
shippingCompany	Shipping company	String	150	No
sellerDocument	Seller document	Document	-	No

Payment

Represents a payment method.

Fields	Description	Type	Length	Required
type	Payment type	Integer	-	Yes
value	Payment value	Float	-	Yes
currency	Currency used	Integer	-	No
sequential	Payment sequential number	Integer	-	No
paymentDate	Payment date	DateTime	-	No
installments	Number of installments	Integer	-	No
payableType	Payment category within the segment: VOUCHER, SUBSCRIPTION, etc	String	150	No
interestRate	Interest rate applied to the payment	Float	-	No
interestValue	Value of interest applied	Float	-	No
visaCheckoutUserId	Visa Checkout user identifier	String	200	No
digitalWalletCode	Digital wallet code used	String	200	No
voucherOrderOrigin	Voucher order origin	String	200	No
subAcquirer	Subacquirer responsible for the payment	String	200	No
bankAuthentication	Bank authentication information	String	200	No
card	Credit card information	Card	-	Yes

Card

Represents credit card information.

Fields	Description	Type	Length	Required
ownerName	Cardholder name	String	150	Yes
number	Card number	String	200	No
hash	Card number hash	String	50	No
bin	Card BIN (Bank Identification Number)	String	12	Yes
end	Last digits of the card	String	4	Yes
type	Card type	Integer	-	No
expirationDate	Card expiration date	String	50	No
document	Document associated with the card	Document	-	No

Document

Represents a document associated with an entity.

Fields	Description	Type	Length	Required
type	Document type	Integer	-	Yes
number	Document number	String	18	Yes
documentTypeCustomer	Customer type associated with the document	String	50	No
authority	Document issuing authority	String	100	No
authorityState	Issuing authority state	String	5	No
issueDate	Document issue date	String	11	No

Address

⚠️
Required fields rule: When the fullAddress field is provided, all other fields in the Address object become optional. If the fullAddress field is not provided, the fields type, street, number, city, state, zipCode and country become required.

Represents an address.

Fields	Description	Type	Length	Required
type	Address type	String	-	No
addressId	Address identifier	String	150	No
street	Street name	String	200	No
number	Address number	String	15	No
district	District	String	150	No
city	City	String	150	No
state	State	String	5	No
zipcode	Zip code (00000-000)	String	10	No
country	Country	String	150	No
additionalInformation	Additional information	String	500	No
reference	Address reference	String	500	No
latitude	Address latitude	String	100	No
longitude	Address longitude	String	100	No
fullAddress	Full address	String	500	No

Phone

Represents information about a phone associated with an entity.

Fields	Description	Type	Length	Required
type	Phone type	Integer	-	No
countryCode	Country code	String	5	No
areaCode	Area code	String	5	Yes
number	Phone number	String	15	Yes
extension	Phone extension	String	10	No

AirTravel

Represents air travel information

Fields	Description	Type	Required
passengers	List of air travel passengers	Passenger Array	Yes
connections	List of itinerary connections/segments	Connection Array	Yes

Passenger

Represents passenger information

Fields	Description	Type	Length	Required
name	Passenger name	String	100	Yes
documentType	Document type	Integer	-	Yes
documentNumber	Document number	String	50	Yes
companyMileCard	Company mileage card	String	50	No
MileCard	Personal mileage card	String	50	No
gender	Passenger gender	String	1	No
birthDate	Passenger birthdate	DateTime	-	No
cpf	Passenger CPF	String	11	No

Connection

Represents connection information

Field	Description	Type	Length	Required
company	Airline company	String	50	No
flightNumber	Flight number	Integer	-	No
date	Flight date	DateTime	-	Yes
seatClass	Seat class	String	10	No
origin	Origin airport	String	5	Yes
destination	Destination airport	String	5	Yes
boarding	Boarding date/time	DateTime	-	Yes
arriving	Arrival date/time	DateTime	-	Yes
fareClass	Fare class	String	25	No

PaymentLink

Represents the payment link information

Field	Description	Type	Length	Required
flagInternationalTransaction	International transaction flag	String	200	No
linkURL	Link url	String	200	No
linkDevice	Device that generated the link	String	200	No
cluster	Cluster/segmentation	String	200	No

Seller

Represents the seller/partner information

Field	Description	Type	Length	Required
sellerID	Store/seller identifier	String	200	No
sellerScore	Seller/partner score	String	200	No
sellerCNAE	Seller/partner business activity code (CNAE)	String	200	No
sellerAccreditationDate	Seller/partner accreditation date	DateTime	-	No
sellerMerchantEmail	Email of the seller/partner representative	String	150	No
sellerMerchantDocument	Document of the seller/partner representative	String	50	No
sellerMerchantDDD	Area code (DDD) of the seller/partner representative	String	10	No
sellerMerchantPhoneNumber	Phone number of the seller/partner representative	String	15	No
sellerAccessionDate	Seller/partner link accession date	DateTime	-	No
sellerPaymentDays	Number of days for payment to the seller/partner	Interger	-	No
sellerPartnersName	Information about the company’s partners (CNPJ owners)	String	200	No
sellerCluster	Seller cluster/segmentation	String	200	No

Example Request

POST https://homologapix.clearsale.com.br/connect/v1/Integration/{{integrationId}}
Accept: application/json
Content-Type: application/json

{
  "transaction": {
    "code": "string",
    "date": "2025-09-25T15:42:34.935Z",
    "email": "string",
    "status": 0,
    "ipAddress": "string",
    "origin": "string",
    "observation": "string"
  },
  "transactionValue": {
    "totalValue": 0
  },
  "device": {
    "fingerprint": {
      "sessionId": "string"
    }
  },
  "billing": {
    "type": 0,
    "name": "string",
    "email": "string",
    "gender": "string",
    "birthdate": "2025-09-25T15:42:34.935Z",
    "documents": [
      {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    ],
    "address": {
      "type": "string",
      "addressId": "string",
      "street": "string",
      "number": "string",
      "district": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "country": "string",
      "additionalInformation": "string",
      "reference": "string",
      "latitude": "string",
      "longitude": "string",
      "fullAddress": "string"
    },
    "phones": [
      {
        "type": 0,
        "countryCode": "string",
        "areaCode": "string",
        "number": "string",
        "extension": "string"
      }
    ]
  },
  "shipping": {
    "type": 0,
    "price": 0,
    "name": "string",
    "email": "string",
    "gender": "string",
    "birthdate": "2025-09-25T15:42:34.935Z",
    "clientId": "string",
    "deliveryType": 0,
    "deliveryTime": "string",
    "documents": [
      {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    ],
    "address": {
      "type": "string",
      "addressId": "string",
      "street": "string",
      "number": "string",
      "district": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "country": "string",
      "additionalInformation": "string",
      "reference": "string",
      "latitude": "string",
      "longitude": "string",
      "fullAddress": "string"
    },
    "phones": [
      {
        "type": 0,
        "countryCode": "string",
        "areaCode": "string",
        "number": "string",
        "extension": "string"
      }
    ]
  },
  "items": [
    {
      "code": "string",
      "name": "string",
      "description": "string",
      "categoryId": 0,
      "categoryName": "string",
      "barCode": "string",
      "value": 0,
      "quantity": 0,
      "isGift": true,
      "sellerName": "string",
      "sellerSegment": "string",
      "isMarketPlace": "string",
      "shippingCompany": "string",
      "sellerDocument": {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    }
  ],
  "payments": [
    {
      "type": 0,
      "value": 0,
      "currency": 0,
      "sequential": 0,
      "paymentDate": "2025-09-25T15:42:34.935Z",
      "installments": 0,
      "payableType": "string",
      "interestRate": 0,
      "interestValue": 0,
      "visaCheckoutUserId": "string",
      "digitalWalletCode": "string",
      "voucherOrderOrigin": "string",
      "subAcquirer": "string",
      "bankAuthentication": "string",
      "card": {
        "ownerName": "string",
        "number": "string",
        "hash": "string",
        "bin": "string",
        "end": "string",
        "type": 0,
        "expirationDate": "string",
        "document": {
          "type": 0,
          "number": "string",
          "documentTypeCustomer": "string",
          "authority": "string",
          "authorityState": "string",
          "issueDate": "string"
        }
      }
    }
  ],
  "airTravel": {
    "passengers": [
      {
        "name": "string",
        "documentType": 0,
        "documentNumber": "string",
        "companyMileCard": "string",
        "mileCard": "string",
        "gender": "string",
        "birthDate": "2025-09-25T15:42:34.935Z",
        "cpf": "string"
      }
    ],
    "connections": [
      {
        "company": "string",
        "flightNumber": 0,
        "date": "2025-09-25T15:42:34.935Z",
        "seatClass": "string",
        "origin": "string",
        "destination": "string",
        "boarding": "2025-09-25T15:42:34.935Z",
        "arriving": "2025-09-25T15:42:34.935Z",
        "fareClass": "string"
      }
    ]
  },
  "paymentLink": {
    "flagInternationalTransaction": "string",
    "linkURL": "string",
    "linkDevice": "string",
    "cluster": "string"
  },
  "seller": {
    "sellerID": "string",
    "sellerScore": "string",
    "sellerCNAE": "string",
    "sellerAccreditationDate": "2025-12-12T13:29:22.039Z",
    "sellerMerchantEmail": "string",
    "sellerMerchantDocument": "string",
    "sellerMerchantDDD": "string",
    "sellerMerchantPhoneNumber": "string",
    "sellerAccessionDate": "2025-12-12T13:29:22.039Z",
    "sellerPaymentDays": 0,
    "sellerPartnersName": "string",
    "sellerCluster": "string"
  }
}

POST Integration/{integrationId}

Endpoint Authentication

Integration Identification by Module

Synchronous and Asynchronous Modules

Synchronous Module Operation

Asynchronous Module Operation

Configuration for Staging Environment

Available Modules

Default Score Configuration

Default Status Configuration

Webhook Configuration

Schema Request

Transaction

Transaction Value

Device

Fingerprint

Billing

Shipping

Item

Payment

Card

Document

Address

Phone

AirTravel

Passenger

Connection

PaymentLink

Seller

Example Request

POST Integration/`{integrationId}`