- Home
- Buy Checker
Buy Checker
Última atualização: 13 de Março de 2024
Buy Checker
Last update: 13th March, 2024
Introdução
As APIs do Buy Checker oferecem detalhes de transações e permitem o compartilhamento de informações sobre o estabelecimento comercial e a transação com os titulares de cartão. Com essas soluções é possível prevenir chargebacks e aprimorar a satisfação do cliente.
Introduction
The Buy Checker APIs provide transaction details and allow you to share merchant and transaction information with cardholders. With these solutions, it is possible to prevent chargebacks and improve customer satisfaction.
Operações API
API Operations
Autenticação do Token
Todas as requisições submetidas à nossa API devem ser realizadas através de um token de 2048 caracteres.
O token é gerado através de um usuário e senha que deve ser fornecido pela ClearSale.
Entre em contato com o seu consultor de vendas para maiores informações.
Na autenticação, além do token retornamos sua data de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nessa data de expiração.
Para o recebimento desse dado é necessário que reserve um espaço de 2048 caracteres. Só gere um novo token após a expiração do seu token atual.
Request
POST https://apix.clearsale.com.br/authenticate
Content-Type: application/json
{
"name": "{Your User}",
"password": "{Your Password}"
}POST https://homologapix.clearsale.com.br/authenticate
Content-Type: application/json
{
"name": "{Your User}",
"password": "{Your Password}"
}Response
200 OK
Content-Type: application/json; charset=utf-8
{
"Token": "{Token value}",
"ExpirationDate": "{Token expiration date}"
} Token Authentication
All sent requests must be realize through a 2048 char token.
A token is generate through a user login and a password that are sent by ClearSale.
Please contact your sales consultant for more information.
During the authentication, the expiration date is sent. It is necessary that you consider in your development the management of the useful life of the token based on it expiration date.
To receive this data, it is necessary to reserve a space of 2048 characters. Only generate a new token after your current token has expired.
Request
POST https://apix.clearsale.com.br/authenticate
Content-Type: application/json
{
"name": "{Your User}",
"password": "{Your Password}"
}POST https://homologapix.clearsale.com.br/authenticate
Content-Type: application/json
{
"name": "{Your User}",
"password": "{Your Password}"
}Response
200 OK
Content-Type: application/json; charset=utf-8
{
"Token": "{Token value}",
"ExpirationDate": "{Token expiration date}"
} Busca para Backoffice
Request
POST https://api-buychecker.clearsale.com.br/v1/transactions/backoffice/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"transactionAmount": "100.56",
"transactionDateTime": "2017-03-22T13:38:59.9894222",
"cardAcceptorName": "cardAcceptorNameExample",
"transactionId": "123456",
"acquirerReferenceNumber": "20292029202920292029001",
"issuerAuthorizationCode": "123456"
}POST https://api-buychecker-hml.clearsale.com.br/v1/transactions/backoffice/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"transactionAmount": "100.56",
"transactionDateTime": "2017-03-22T13:38:59.9894222",
"cardAcceptorName": "cardAcceptorNameExample",
"transactionId": "123456",
"acquirerReferenceNumber": "20292029202920292029001",
"issuerAuthorizationCode": "123456"
}Response
Content-Type: application/json
{
"merchantName": "merchantNameExample",
"date": "2017-03-22T13:38:59.9894222",
"amount": 100.52,
"billing": {
"billingName": "billingNameExample",
"address":{
"street": "streetExample",
"number": "11",
"city": "cityExample",
"postalCode": "24452001",
"countrySubdivisionCode": "CA",
"neighborhood": "neighborhoodExample"
},
"email": "emailExample@gmail.com",
"phone": "21999999999"
},
"purchase": {
"receiver": "receiverExample",
"email": "emailExample@gmail.com",
"shippingAddress": {
"street": "streetExample",
"number": "11",
"city": "cityExample",
"postalCode": "24452001",
"countrySubdivisionCode": "CA",
"neighborhood": "neighborhoodExample"
},
"items":[{
"description": "descriptionExample",
"amount": 100.52,
"quantity": 1
}]
}
}Search for Backoffice
Request
POST https://api-buychecker.clearsale.com.br/v1/transactions/backoffice/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"transactionAmount": "100.56",
"transactionDateTime": "2017-03-22T13:38:59.9894222",
"cardAcceptorName": "cardAcceptorNameExample",
"transactionId": "123456",
"acquirerReferenceNumber": "20292029202920292029001",
"issuerAuthorizationCode": "123456"
}POST https://api-buychecker-hml.clearsale.com.br/v1/transactions/backoffice/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"transactionAmount": "100.56",
"transactionDateTime": "2017-03-22T13:38:59.9894222",
"cardAcceptorName": "cardAcceptorNameExample",
"transactionId": "123456",
"acquirerReferenceNumber": "20292029202920292029001",
"issuerAuthorizationCode": "123456"
}Response
Content-Type: application/json
{
"merchantName": "merchantNameExample",
"date": "2017-03-22T13:38:59.9894222",
"amount": 100.52,
"billing": {
"billingName": "billingNameExample",
"address":{
"street": "streetExample",
"number": "11",
"city": "cityExample",
"postalCode": "24452001",
"countrySubdivisionCode": "CA",
"neighborhood": "neighborhoodExample"
},
"email": "emailExample@gmail.com",
"phone": "21999999999"
},
"purchase": {
"receiver": "receiverExample",
"email": "emailExample@gmail.com",
"shippingAddress": {
"street": "streetExample",
"number": "11",
"city": "cityExample",
"postalCode": "24452001",
"countrySubdivisionCode": "CA",
"neighborhood": "neighborhoodExample"
},
"items":[{
"description": "descriptionExample",
"amount": 100.52,
"quantity": 1
}]
}
}Busca para Aplicativos
Request
POST https://api-buychecker.clearsale.com.br/v1/transactions/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"TransactionAmount": "100.56",
"TransactionDateTime": "2017-03-22T13:38:59.9894222",
"CardAcceptorName": "CardAcceptorNameExample",
"TransactionId": "123456",
"AcquirerReferenceNumber": "20292029202920292029001",
"IssuerAuthorizationCode": "123456"
}POST https://api-buychecker-hml.clearsale.com.br/v1/transactions/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"TransactionAmount": "100.56",
"TransactionDateTime": "2017-03-22T13:38:59.9894222",
"CardAcceptorName": "CardAcceptorNameExample",
"TransactionId": "123456",
"AcquirerReferenceNumber": "20292029202920292029001",
"IssuerAuthorizationCode": "123456"
}Response
Content-Type: application/json
{
"merchantName": "merchantNameExample",
"date": "2017-03-22T13:38:59.9894222",
"amount": 100.52,
"items":[{
"description": "descriptionExample",
"amount": 100.52,
"quantity": 1
}]
}
}Search for Apps
Request
POST https://api-buychecker.clearsale.com.br/v1/transactions/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"TransactionAmount": "100.56",
"TransactionDateTime": "2017-03-22T13:38:59.9894222",
"CardAcceptorName": "CardAcceptorNameExample",
"TransactionId": "123456",
"AcquirerReferenceNumber": "20292029202920292029001",
"IssuerAuthorizationCode": "123456"
}POST https://api-buychecker-hml.clearsale.com.br/v1/transactions/search
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
"cardFirstSix": "123456",
"cardLastFour": "1234",
"TransactionAmount": "100.56",
"TransactionDateTime": "2017-03-22T13:38:59.9894222",
"CardAcceptorName": "CardAcceptorNameExample",
"TransactionId": "123456",
"AcquirerReferenceNumber": "20292029202920292029001",
"IssuerAuthorizationCode": "123456"
}Response
Content-Type: application/json
{
"merchantName": "merchantNameExample",
"date": "2017-03-22T13:38:59.9894222",
"amount": 100.52,
"items":[{
"description": "descriptionExample",
"amount": 100.52,
"quantity": 1
}]
}
}Descrição de Campos
Fields Description
Objeto RequestDetail
| Propriedade | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| CardFirstSix | Primeiros seis dígitos do cartão | String | 6 | S |
| CardLastFour | Últimos quatro dígitos do cartão | String | 4 | S |
| TransactionAmount | Valor da compra | Decimal | S | |
| TransactionDateTime | Data da realização da compra | DateTime | S | |
| CardAcceptorName | Nome que consta na fatura | String | S | |
| TransactionId | ID da transação | String | N | |
| AcquirerReferenceNumber | Número de referência do adquirente | String | 23 | S |
| IssuerAuthorizationCode | Código de autorização do emissor do cartão | String | 6 | S |
Object RequestDetail
| Property | Description | Type | Size | Mandatory |
|---|---|---|---|---|
| CardFirstSix | First six digits of the card | String | 6 | Y |
| CardLastFour | Last four digits of the card | String | 4 | Y |
| TransactionAmount | Transaction amount | Decimal | Y | |
| TransactionDateTime | Purchase date | DateTime | Y | |
| CardAcceptorName | Merchant 'doing business as' name | String | Y | |
| TransactionId | Transaction ID | String | N | |
| AcquirerReferenceNumber | Acquired reference number of the transaction | String | 23 | Y |
| IssuerAuthorizationCode | Issuer authorization code | String | 6 | Y |
Objeto TransactionDetail
| Propriedade | Descrição | Tipo |
|---|---|---|
| MerchantName | Nome da loja | String |
| Date | Data da transação | DateTime |
| Amount | Valor da compra | decimal |
| E-mail cadastrado na compra | String | |
| Phone | Telefone cadastrado na compra | String |
| Billing | Objeto Billing | Billing |
| Purchase | Objeto Purchase | Purchase |
Object TransactionDetail
| Property | Description | Type |
|---|---|---|
| MerchantName | Merchant name | String |
| Date | Purchase date | DateTime |
| Amount | Purchase amount | decimal |
| Email registred in the purchase | String | |
| Phone | Phone number registred in the purchase | String |
| Billing | Object Billing | Billing |
| Purchase | Object Purchase | Purchase |
Objeto Address
| Propriedade | Descrição | Tipo |
|---|---|---|
| Street | Nome do logradouro | String |
| Number | Número da residência | String |
| City | Cidade | String |
| PostalCode | Código postal (CEP) | String |
| CountrySubdivisionCode | Código de identificação dos estados | String |
| Neighborhood | Bairro | String |
Object Address
| Property | Description | Type |
|---|---|---|
| Street | Street name | String |
| Number | Residence number | String |
| City | City | String |
| PostalCode | Postal Code | String |
| CountrySubdivisionCode | State identification code | String |
| Neighborhood | Neighborhood | String |
Objeto Billing
| Propriedade | Descrição | Tipo |
|---|---|---|
| BillingName | Nome do titular do cartão | String |
| E-mail relacionado ao titular | String | |
| Phone | Telefone do titular | String |
| Address | Objeto Address | Address |
Object Billing
| Property | Description | Type |
|---|---|---|
| BillingName | Cardholder name | String |
| Cardholder e-mail | String | |
| Phone | Cardholder phone number | String |
| Address | Object Address | Address |
Objeto Purchase
| Propriedade | Descrição | Tipo |
|---|---|---|
| Receiver | Nome do recebedor | String |
| E-mail do recebedor | String | |
| Address | Objeto Address | Address |
Object Purchase
| Property | Description | Type |
|---|---|---|
| Receiver | Recipient name | String |
| Recipient email | String | |
| Address | Object Address | Address |
Objeto Items
| Propriedade | Descrição | Tipo |
|---|---|---|
| Description | Descrição do item | String |
| Amount | Valor do item | Decimal |
| Quantity | Quantidade de itens | Decimal |
Object Items
| Property | Description | Type |
|---|---|---|
| Description | Item description | String |
| Amount | Item value | Decimal |
| Quantity | Quantity of items | Decimal |
Resolução de Problemas
Troubleshooting
Ausência de usuário/senha
/StatusCode: 400 (Bad Request)
Content-Type: application/json
{
"Message": "The request is invalid.",
"ModelState": {
"< JPath_of_Property >": [
"The < Property > field is required."
]
}
}Usuário/senha incorretos
/HttpCode: 401 (Unauthorized)
Content-Type: text/plain
UserNotFoundToken inválido
/StatusCode: 401 (Unauthorized)Token expirado
/StatusCode: 401 (Unauthorized)Campos obrigatórios não preenchidos
/StatusCode: 400 (Bad Request)
Content-Type: application/json
{
"title": "Request is not valid",
"status": 400,
"detail": "One or more invalid fields provided",
"invalidFields": [
{
"name": "< Field_Name >",
"reason": "'< Field_Name >' must be informed"
}
]
}Transação não encontrada
/StatusCode: 404 (Not Found)
Content-Type: application/json
{
"title": "No transaction found",
"status": 404,
"detail": "No transaction was found for the specified search parameters"
}Múltiplas transações encontradas
/StatusCode: 409 (Conflict)
Content-Type: application/json
{
"title": "Multiple transactions found",
"status": 409,
"detail": "More than one transaction was found for specified search parameters."
}Erro interno do servidor
/StatusCode: 500 (Internal Server Error)
Content-Type: application/json
{
"title": "Internal server error",
"status": 500,
"detail": "An internal error has ocurred. If it happens again, contact support.",
"exception": "< Details_of_error >"
}Missing username/password
/StatusCode: 400 (Bad Request)
Content-Type: application/json
{
"Message": "The request is invalid.",
"ModelState": {
"< JPath_of_Property >": [
"The < Property > field is required."
]
}
}Incorrect username/password
/HttpCode: 401 (Unauthorized)
Content-Type: text/plain
UserNotFoundInvalid token
/StatusCode: 401 (Unauthorized)Token expired
/StatusCode: 401 (Unauthorized)Required fields not filled
/StatusCode: 400 (Bad Request)
Content-Type: application/json
{
"title": "Request is not valid",
"status": 400,
"detail": "One or more invalid fields provided",
"invalidFields": [
{
"name": "< Field_Name >",
"reason": "'< Field_Name >' must be informed"
}
]
}Transaction not found
/StatusCode: 404 (Not Found)
Content-Type: application/json
{
"title": "No transaction found",
"status": 404,
"detail": "No transaction was found for the specified search parameters"
}Multiple transactions found
/StatusCode: 409 (Conflict)
Content-Type: application/json
{
"title": "Multiple transactions found",
"status": 409,
"detail": "More than one transaction was found for specified search parameters."
}Internal server error
/StatusCode: 500 (Internal Server Error)
Content-Type: application/json
{
"title": "Internal server error",
"status": 500,
"detail": "An internal error has ocurred. If it happens again, contact support.",
"exception": "< Details_of_error >"
}