BNPL BACKGROUND TRUST

Última atualização: 28 de Maio de 2024

Introdução

Buy Now Pay Later, ou, em tradução livre, “Compre agora, pague depois”, é um método de pagamento digital parcelado semelhante a um crediário digital, para compras online mais comum em e-commerces. Alguns também têm chamado o modelo de parcelamento inteligente.

A grande diferença entre o BNPL e o crediário convencional é a tecnologia por trás deste produto, que permite fazer a análise e a liberação de crédito de forma instantânea e digital, inclusive, utilizando na análise, informações da própria transação como os produtos que estão sendo comprados. Não é mais uma operação física, mas também funciona para transações em estabelecimentos físicos.

Brasileiros estão acostumados a pagar em parcelas, mas a grande maioria da população ainda não é atendida pelos modelos existentes de pagamento além do cartão de crédito. O modelo de Buy Now Pay Later impacta principalmente pessoas que não tem cartão de crédito (como geração Z), pessoas que tem cartão de crédito, mas o limite é baixo e pessoas que não querem, ou preferem não usar, cartão de crédito.

Descrição

O produto BNPL Background Trust foi desenvolvido para que no momento da jornada de pagamento no modelo de BNPL, o tomador de decisão para aprovação de crédito ou averiguação de fraude, possa interagir com o nosso serviço e se beneficiar de todo know-how que a Clear Sale pode oferecer.
Através de uma cominicação via HTTP - API REST entregamos scores e outras informações de apoio para que a análise de aprovação possa ser a mais robusta e satisfatória possível.

Queremos entregar um produto que otimize a jornada no modelo BNPL, oferecendo uma forma unificada, segura e ágil de solução. E que auxilie no crescimento das vendas através deste meio de pagamento
Para isso, entendemos que nossa abordagem traz consigo vários ganhos nesse processo:

  • Traremos agilidade ao concentrar várias áreas de inteligência da ClearSale em um único gateway inteligente fornecendo mais informações no menor tempo possível.
  • Traremos simplicidade ao fornecer informações claras e de alta relevância nas tomadas de decisão.
  • Traremos ainda mais segurança para o processo de BNPL através do Know-How Clear Sale.

Segurança

Todas as requisições submetidas à nossa API devem conter um token de autenticação gerado através de um usuário e senha que devem ser fornecidos pela ClearSale. Neste processo, além do token retornamos seu tempo de expiração em segundos e é necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração.
Além disso, também aplicamos uma configuração de restrição de IP em nossos serviços para que somente um escopo conhecido de endereços cadastrados possa ter seu acesso garantido, assim, em produção, é necessário realizar previamente o cadastros dos IPs. Devido a esta camada de segurança, toda a integração com a nossa API deve ser feita via Backend.

Autorização

Para enviar uma requisição é necessário que o cliente esteja cadastrado no SSO (Single Sign On) da ClearSale, durante o contato para homologação e integração solicite suas credenciais.

Também é necessário que você considere em seu desenvolvimento a gestão da vida útil do token com base no tempo de expiração que é retornado em segundos.

Request


POST  https://bnpl-backgroundtrust.clear.sale/api/v1/identity/auth/token HTTP/1.1 
Content-Type:application/x-www-form-urlencoded

client_id:'client_id'
client_secret:'client_secret''
grant_type:client_credentials
scope:'escopo'


POST  https://bnpl-backgroundtrust-hml.clear.sale/api/v1/identity/auth/token HTTP/1.1 
Content-Type:application/x-www-form-urlencoded

client_id:'client_id'
client_secret:'client_secret''
grant_type:client_credentials
scope:'escopo'
Response
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "token": "...fhgytudX345f.... ",
        "expiresIn": 000 //valor retornado em segundos
    }
}

Análise das transações no contexto de concessão de fraude.


As transações analizadas dentro desse contexto, retornam um conjunto de informações que servem de apoio à averiguação de possível fraude.

Referência de API

Solicita as informações de análise de fraude informando os dados da transação de compra.

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v1/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
POST https://bnpl-backgroundtrust-hml.clear.sale/api/v1/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
Response

Requisição realizada com sucesso.

HTTP/1.1 200 Created
Content-Type: application/json; charset=utf-8
{
    "data": {
        "id": "705fc42d-1e43-4d07-b159-331b35b8c03a",
        "referenceDate": "2024-05-29T13:06:08.3551704+00:00",
        "type": 1,
        "document": "12345678999",
        "documentType": "CPF",
        "areaCode": "32",
        "phone": "+55 (32) 912345678",
        "verifiedPhone": false,
        "sendOption": "",
        "address": {
            "zipCode": "12345678",
            "street": "Johathan Key",
            "number": "99",
            "complement": "Laborum sunt dolore et assumenda aut et quis.",
            "district": "East Robin",
            "city": "Yuba City",
            "state": "SP",
            "country": "",
            "physicalDelivery": ""
        },
        "email": "Freddy33@yahoo.com",
        "verifiedEmail": false,
        "sessionId": "",
        "additionalInformation": {
            "transaction": null,
            "item": null,
            "price": null,
            "customerName": null,
            "other": null
        },
        "creationDate": "2024-05-29T13:06:08.355077+00:00",
        "results": {
            "score": {
                "value": 59.79,
                "reason": "Initial",
                "date": "0001-01-01T00:00:00",
                "timeline": ""
            },
            "validation": {
                "smsVerification": false,
                "emailVerification": false,
                "tokenSms": "",
                "tokenEmail": ""
            },
            "ratings": [
                {
                    "value": 1.0,
                    "reason": "Initial",
                    "date": "0001-01-01T00:00:00",
                    "relatedTo": [
                        "Email",
                        "ZipCode"
                    ],
                    "timeline": ""
                },
                {
                    "value": 3.0,
                    "reason": "Initial",
                    "date": "0001-01-01T00:00:00",
                    "relatedTo": [
                        "Phone",
                        "ZipCode"
                    ],
                    "timeline": ""
                },
                {
                    "value": 2.0,
                    "reason": "Initial",
                    "date": "0001-01-01T00:00:00",
                    "relatedTo": [
                        "Document",
                        "Phone"
                    ],
                    "timeline": ""
                },               
            ],
            "insights": [
                {
                    "code": "GER2106",
                    "description": "O CPF já foi envolvido em fraude pela última vez há mais de 3 anos ",
                    "type": "CPF",
                    "category": "Fraude CPF",
                    "relevance": "Alerta",
                    "relatedTo": [
                        "Document"
                    ]
                },
                {
                    "code": "GER2152",
                    "description": "CPF com alta incidência de transações positivas",
                    "type": "CPF",
                    "category": "Característica CPF",
                    "relevance": "Positivo",
                    "relatedTo": [
                        "Document"
                    ]
                },
                {
                    "code": "GER2117",
                    "description": "Estado de emissão do CPF: SP",
                    "type": "CPF",
                    "category": "Característica CPF",
                    "relevance": "Neutro",
                    "relatedTo": [
                        "Document"
                    ]
                },
            ]
        },
        "clientIpAddress": "195.17.236.199"
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error

Informações sobre os parâmetros de entrada

Nome Descrição Tipo Tamanho Obrigatório
Consumer Objeto com as informações do consumidor. Consumer Sim
Order Objeto com as informações do pedido. Order Não
Merchant Objeto com as informações do lojista. Merchant Não

Consumer

Nome Descrição Tipo Tamanho Obrigatório
Document Número do CPF do consumidor. String [ 11 .. 15 ] Sim
DateOfBirth Data de nascimento do consumidor. DateTime Não
Email Endereço de email do consumidor. String [ 0 .. 19 ] Não
IP Número de IP do dispositivo do consumidor. String [ 0 .. 30 ] Não
DeviceId Identificador do dispositivo utilizado. String [ 0 .. 30 ] Não
Address Endereço residencial do consumidor. Address Não

Order

Nome Descrição Tipo Tamanho Obrigatório
Price Valor total do pedido. Decimal Não
Items Lista de items do pedido. Items Sim
Shipping Informações sobre o envio do pedido. Shipping Não

Merchant

Nome Descrição Tipo Tamanho Obrigatório
Document Número de CNPJ do estabelecimento. String [ 14 .. 20 ] Sim
CorporateName Razão social do estabelecimento. String 200 Não
Email Endereço de email do estabelecimento. String [ 0 .. 19 ] Não
Phone Número do telefone do estabelecimento no formato +55 (32) 91234-5678 String 19 Não
Address Endereço do estabelecimento. Address Não

Item

Nome Descrição Tipo Tamanho Obrigatório
Code Código de identificação do item String Sim
Name Nome do item. String Sim
Description Descrição do item. String Não
Price Valor do item. Decimal Sim
Quantity Quantidade do item. Int Não

Shipping

Nome Descrição Tipo Tamanho Obrigatório
ReceiverName Nome de uma pessoa que também poderá receber o produto String Não
Price Valor do frete. Decimal Não
Note Campo para alguma observação relativa a entrega. String Não
Address Endereço de entrega. Address Sim

Address

Nome Descrição Tipo Tamanho Obrigatório
ZipCode Código postal (Sem pontuação) String 8 Sim
Street Nome da rua ou avenida. String Não
Number Número da residência. String Não
Complement Complemento do endereço. String Não
District Nome do bairro, logradouro ou distrito. String Não
City Cidade. String Não
State Estado. String Não
Country País. String Não
Nome Descrição Tipo
Message Campo para alguma mensagem de erro ou alerta. String
Success Campo indicando se a requisição ocorreu com sucesso. Boolean
Result Identificador único da transação. Guid

Referência de API (V2)

Solicita as informações de análise de fraude dividido entre endpoints de Score, Ratings e Insights.

Transaction

O endpoint '/transactions' (V2) deve ser chamado antes dos endpoints abaixo de score, ratings e insights, para que seja possível obter o transaction_id necessário na rota dos próximos.

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v2/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
POST https://bnpl-backgroundtrust-hml.clear.sale/api/v2/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
Response

Requisição realizada com sucesso.

HTTP/1.1 200 Created
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "4be98e0e-7845-4f41-9376-63a48fa3155a",
        "document": "10439292662",
        "createdAt": "2024-07-25T18:05:51.1188432+00:00"
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error

Score

Para obter o score, passamos o transaction_id optido anteriormente no endpoint '/transactions' para o seguinte endpoint: '.../api/v2/fraud/transactions/{transaction_Id}/scores'

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v2/fraud/transactions/{transaction_id}/scores HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}

POST https://bnpl-backgroundtrust-hml.clear.sale/api/v2/fraud/transactions/{transaction_id}/scores HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
Response

Requisição realizada com sucesso.

HTTP/1.1 200 Created
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "4be98e0e-7845-4f41-9376-63a48fa3155a",
        "createdAt": "2024-07-25T18:07:33.392Z",
        "score": 21.68
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error

Ratings

Para obter os valores de ratings, passamos o transaction_id optido anteriormente no endpoint '/transactions' para o seguinte endpoint: '.../api/v2/fraud/transactions/{transaction_Id}/ratings'

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v2/fraud/transactions/{transaction_id}/ratings HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}

POST https://bnpl-backgroundtrust-hml.clear.sale/api/v2/fraud/transactions/{transaction_id}/ratings HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
Response

Requisição realizada com sucesso.

HTTP/1.1 200 Created
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "4be98e0e-7845-4f41-9376-63a48fa3155a",
        "createdAt": "2024-07-25T18:10:54.177Z",
        "ratings": [
            {
                "value": 1.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Email",
                    "ZipCode"
                ]
            },
            {
                "value": 3.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Phone",
                    "ZipCode"
                ]
            },
            {
                "value": 2.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "value": 3.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Phone",
                    "Email"
                ]
            },
            {
                "value": 2.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "value": 1.0,
                "reason": "Initial",
                "createdAt": "2024-07-25T18:10:54.177Z",
                "relatedTo": [
                    "Document",
                    "ZipCode"
                ]
            }
        ]
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error

Insights

Para obter o insights, passamos o transaction_id optido anteriormente no endpoint '/transactions' para o seguinte endpoint: '.../api/v2/fraud/transactions/{transaction_Id}/insights'

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v2/fraud/transactions/{transaction_id}/insights HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}

POST https://bnpl-backgroundtrust-hml.clear.sale/api/v2/fraud/transactions/{transaction_id}/insights HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
Response

Requisição realizada com sucesso.

HTTP/1.1 200 Created
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "4be98e0e-7845-4f41-9376-63a48fa3155a",
        "createdAt": "2024-07-25T18:11:23.7356151+00:00",
        "insights": [
            {
                "code": "GER2106",
                "description": "O CPF já foi envolvido em fraude pela última vez há mais de 3 anos ",
                "type": "CPF",
                "category": "Fraude CPF",
                "relevance": "Alerta",
                "relatedTo": [
                    "Document"
                ]
            },
            {
                "code": "GER2152",
                "description": "CPF com alta incidência de transações positivas",
                "type": "CPF",
                "category": "Característica CPF",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document"
                ]
            },
            {
                "code": "GER2117",
                "description": "Estado de emissão do CPF: SP",
                "type": "CPF",
                "category": "Característica CPF",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document"
                ]
            },
            {
                "code": "GER2360",
                "description": "Região de BAIXO risco de fraude",
                "type": "CEP",
                "category": "Gestão de Risco CEP",
                "relevance": "Positivo",
                "relatedTo": [
                    "ZipCode"
                ]
            },
            {
                "code": "DUP3002",
                "description": "A dupla Email + CEP informada foi vista pela última vez entre 1 e 3 meses ",
                "type": "Email CEP",
                "category": "Idade do Par Email CEP",
                "relevance": "Positivo",
                "relatedTo": [
                    "Email",
                    "ZipCode"
                ]
            },
            {
                "code": "DUP3009",
                "description": "A dupla Email + CEP informada foi vista pela primeira vez entre 1 e 3 meses ",
                "type": "Email CEP",
                "category": "Idade do Par Email CEP",
                "relevance": "Alerta",
                "relatedTo": [
                    "Email",
                    "ZipCode"
                ]
            },
            {
                "code": "GER2251",
                "description": "Telefone com incidência de transações positivas",
                "type": "Telefone",
                "category": "Característica Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Phone"
                ]
            },
            {
                "code": "GER2246",
                "description": "Mais que 2 pessoas utilizam este telefone para transações positivas",
                "type": "Telefone",
                "category": "Gestão de Risco Telefone",
                "relevance": "Alerta",
                "relatedTo": [
                    "Phone"
                ]
            },
            {
                "code": "DUP1002",
                "description": "A dupla Telefone + Email informada foi vista pela última vez entre 1 e 3 meses ",
                "type": "Email Telefone",
                "category": "Idade do Par de Email Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Phone",
                    "Email"
                ]
            },
            {
                "code": "DUP1014",
                "description": "A dupla Telefone + Email informada foi vista pela primeira vez há mais de 3 anos ",
                "type": "Email Telefone",
                "category": "Idade do Par de Email Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Phone",
                    "Email"
                ]
            },
            {
                "code": "GER2001",
                "description": "E-mail contém nomes do cliente",
                "type": "Email",
                "category": "Carasterísticas do Email",
                "relevance": "Neutro",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2021",
                "description": "Domínio de E-mail com alto risco de Fraude",
                "type": "Email",
                "category": "Gestão de Risco Email",
                "relevance": "Alerta",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2027",
                "description": "Domínio de E-mail Muito Comum",
                "type": "Email",
                "category": "Gestão de Risco Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2032",
                "description": "Pouca chance de ser um e-mail temporário",
                "type": "Email",
                "category": "Gestão de Risco Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2041",
                "description": "E-mail com histórico positivo com 2 CEPs",
                "type": "Email",
                "category": "Gestão de Risco Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2046",
                "description": "Mais que 1 pessoa utiliza este E-mail para transações positivas",
                "type": "Email",
                "category": "Gestão de Risco Email",
                "relevance": "Neutro",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER2051",
                "description": "E-mail com incidência de transações positivas",
                "type": "Email",
                "category": "Característica Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Email"
                ]
            },
            {
                "code": "GER0060",
                "description": "O DDD e o CPF informados pertencem ao mesmo estado de origem",
                "type": "CPF Telefone",
                "category": "Geolocalização Telefone",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "GER0141",
                "description": "O celular informado é da mesma região que a pessoa transita, com base nos CEPs encontrados no Big Data",
                "type": "CPF Telefone",
                "category": "Geolocalização Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "TEL0001",
                "description": "O telefone informado é um HotPhone da pessoa",
                "type": "CPF Telefone",
                "category": "Vínculo Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "TEL0030",
                "description": "O telefone informado foi utilizado pela pessoa pela última vez entre 1 e 3 meses ",
                "type": "CPF Telefone",
                "category": "Uso Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "TEL0560",
                "description": "O telefone informado foi visto pela primeira vez entre 5 anos e 10 anos",
                "type": "CPF Telefone",
                "category": "Idade Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "TEL0620",
                "description": "O telefone informado foi visto pela última vez entre 1 e 3 meses",
                "type": "CPF Telefone",
                "category": "Idade Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Phone"
                ]
            },
            {
                "code": "EML0001",
                "description": "O E-mail informado é um Hot-Email da pessoa",
                "type": "CPF Email",
                "category": "Vínculo Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "EML0007",
                "description": "Existem outros E-mails possíveis para a pessoa",
                "type": "CPF Email",
                "category": "Vínculo Email",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "EML0030",
                "description": "O E-mail informado foi utilizado pela pessoa pela última vez entre 1 e 3 meses ",
                "type": "CPF Email",
                "category": "Uso Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "EML0550",
                "description": "O E-mail informado foi visto pela primeira vez entre 2 anos e 5 anos",
                "type": "CPF Email",
                "category": "Idade Email",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "EML0620",
                "description": "O E-mail informado foi visto pela última vez entre 1 e 3 meses",
                "type": "CPF Email",
                "category": "Idade Email",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "EML1100",
                "description": "A pessoa possui outros e-mails no mesmo provedor",
                "type": "CPF Email",
                "category": "Vínculo Email",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "Email"
                ]
            },
            {
                "code": "END0002",
                "description": "O CEP informado não é um HotCEP da pessoa",
                "type": "CPF CEP",
                "category": "Vínculo CEP",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "ZipCode"
                ]
            },
            {
                "code": "END0007",
                "description": "Existem outros CEPs possíveis para a pessoa",
                "type": "CPF CEP",
                "category": "Vínculo CEP",
                "relevance": "Neutro",
                "relatedTo": [
                    "Document",
                    "ZipCode"
                ]
            },
            {
                "code": "END0030",
                "description": "O CEP informado foi utilizado pela pessoa pela última vez entre 1 e 3 meses ",
                "type": "CPF CEP",
                "category": "Uso CEP",
                "relevance": "Positivo",
                "relatedTo": [
                    "Document",
                    "ZipCode"
                ]
            },
            {
                "code": "DUP5002",
                "description": "A dupla Telefone + CEP informada foi vista pela última vez entre 1 e 3 meses ",
                "type": "Telefone CEP",
                "category": "Idade do Par Telefone CEP",
                "relevance": "Positivo",
                "relatedTo": [
                    "Phone",
                    "ZipCode"
                ]
            },
            {
                "code": "DUP5011",
                "description": "A dupla Telefone + CEP informada foi vista pela primeira vez entre 6 meses e 1 ano ",
                "type": "Telefone CEP",
                "category": "Idade do Par Telefone CEP",
                "relevance": "Neutro",
                "relatedTo": [
                    "Phone",
                    "ZipCode"
                ]
            },
            {
                "code": "DUP5050",
                "description": "DDD condiz com CEP informado",
                "type": "Telefone CEP",
                "category": "Geolocalização Telefone",
                "relevance": "Positivo",
                "relatedTo": [
                    "Phone",
                    "ZipCode"
                ]
            }
        ]
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error

Análise das transações no contexto de concessão de crédito


As transações analizadas dentro desse contexto, retornam um conjunto de scores que servem de apoio a tomada de decisão na concessão de crédito.

Referência de API

Solicita as informações de análise de concessão de crédito informando os dados da transação de compra.

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v1/credit/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
POST https://bnpl-backgroundtrust-hml.clear.sale/api/v1/credit/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}
Response

A transação foi criada com sucesso.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "date": "2023-06-29T19:16:46.431Z",
        "document": "12345678900",
        "score": 500,
        "digital": true,
        "rank": "g",
        "varietyIndex": 100,
        "behaviourIndex": 200,
        "profileIndex": 300,
        "statusIndex": 400,
        "postalIndex": 500,
        "rapportIndex": 600
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
    "message": "The inputs supplied to the API are invalid",
    "success": false,
    "result": [
        "Document is required",
        "Document must be between 11 and 15 characters"
    ]
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição. 

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de entrada

Nome Descrição Tipo Tamanho Obrigatório
Consumer Objeto com as informações do consumidor. Consumer Sim
Order Objeto com as informações do pedido. Order Não
Merchant Objeto com as informações do lojista. Merchant Não

Consumer

Nome Descrição Tipo Tamanho Obrigatório
Document Número do CPF do consumidor. String [ 11 .. 15 ] Sim
DateOfBirth Data de nascimento do consumidor. DateTime Não
Email Endereço de email do consumidor. String [ 0 .. 19 ] Não
IP Número de IP do dispositivo do consumidor. String [ 0 .. 30 ] Não
DeviceId Identificador do dispositivo utilizado. String [ 0 .. 30 ] Não
Address Endereço residencial do consumidor. Address Não

Order

Nome Descrição Tipo Tamanho Obrigatório
Price Valor total do pedido. Decimal Não
Items Lista de items do pedido. Items Sim
Shipping Informações sobre o envio do pedido. Shipping Não

Merchant

Nome Descrição Tipo Tamanho Obrigatório
Document Número de CNPJ do estabelecimento. String [ 14 .. 20 ] Sim
CorporateName Razão social do estabelecimento. String 200 Não
Email Endereço de email do estabelecimento. String [ 0 .. 19 ] Não
Phone Número do telefone do estabelecimento no formato +55 (32) 91234-5678 String 19 Não
Address Endereço do estabelecimento. Address Não

Item

Nome Descrição Tipo Tamanho Obrigatório
Code Código de identificação do item String Sim
Name Nome do item. String Sim
Description Descrição do item. String Não
Price Valor do item. Decimal Sim
Quantity Quantidade do item. Int Não

Shipping

Nome Descrição Tipo Tamanho Obrigatório
ReceiverName Nome de uma pessoa que também poderá receber o produto String Não
Price Valor do frete. Decimal Não
Note Campo para alguma observação relativa a entrega. String Não
Address Endereço de entrega. Address Sim

Address

Nome Descrição Tipo Tamanho Obrigatório
ZipCode Código postal (Sem pontuação) String 8 Sim
Street Nome da rua ou avenida. String Não
Number Número da residência. String Não
Complement Complemento do endereço. String Não
District Nome do bairro, logradouro ou distrito. String Não
City Cidade. String Não
State Estado. String Não
Country País. String Não
Nome Descrição Tipo
Document Número do CPF do consumidor. String
Score Pontuação relacionada ao número do documento. Int
Digital Parâmetro de classificação que indica se o cliente tem ou não presença digital. Boolean
Rank Total de compras, tipos de cartões usados e CEPs relacionados ao cliente String
VarietyIndex Qualidade e variedade do que o cliente compra. Int
BehaviourIndex Formas de pagamento utilizadas e frequência de compra do cliente. Int
RapportIndex Scores dos CPF relacionados ao cliente. Int
ProfileIndex Tipo de endereço, tipo de device, categoria do cartão do cliente. Int
StatusIndex Características fixas como data e local de nascimento do cliente. Int
PostalIndex Valor e frequência de compras nos CEPs relacionados ao cliente. Int

Avisos e recomendações

📌 Recomendação

Performance - Uso do ambiente de homologação

O Ambiente de homologação deve ser utilizado somente para fims de desenvolvimento, pois o mesmo pode apresentar alguma lentidão, e por restringir as transações a determinados números de CPF.

📌 Recomendação

Segurança - Gerenciamento do token de autorização

Todas as requisições submetidas à nossa API devem conter um token de autenticação gerado através de um usuário e senha que devem ser fornecidos pela ClearSale. Neste processo, além do token retornamos seu tempo de expiração em segundos e é necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração.

📢 Aviso Importante

Segurança - Bloqueio de Ips

Aplicamos uma configuração de restrição de IP em nossos serviços para que somente um escopo conhecido de endereços cadastrados possa ter seu acesso garantido, assim, em produção, é necessário realizar previamente o cadastros dos IPs.

📌 Recomendação

Integração - Números de CPF para testes em homologação no contexto de crédito

Para realizar testes e validações por faixa de score principal, no contexto de crédito utilize os respectivos CPF:

  • 000.235.082-30 para score na faixa 100
  • 003.879.762-30 para score na faixa 200
  • 366.708.678-40 para score na faixa 300
  • 438.415.112-87 para score na faixa 400
  • 032.995.682-56 para score na faixa 500
  • 274.917.408-20 para score na faixa 600
  • 756.097.622-00 para score na faixa 700
  • 013.563.708-29 para score na faixa 800
  • 380.068.688-08 para score na faixa 900

📌 Recomendação

Integração - Números de CPF para testes em homologação no contexto de fraude

Para realizar testes e validações por faixa de score principal, no contexto de fraude utilize os respectivos CPF:

  • XXX.XXX.XXX-X0 para score na faixa 0~10
  • XXX.XXX.XXX-X1 para score na faixa 10~20
  • XXX.XXX.XXX-X2 para score na faixa 20~30
  • XXX.XXX.XXX-X3 para score na faixa 30~40
  • XXX.XXX.XXX-X4 para score na faixa 40~50
  • XXX.XXX.XXX-X5 para score na faixa 50~60
  • XXX.XXX.XXX-X6 para score na faixa 60~70
  • XXX.XXX.XXX-X7 para score na faixa 70~80
  • XXX.XXX.XXX-X8 para score na faixa 80~90
  • XXX.XXX.XXX-X9 para score na faixa 90~100

Dúvidas ou problemas técnicos

Em caso de dúvidas ou problemas técnicos, fale com a gente através do e-mail suporte.bnpl@clear.sale