Pular para o conteúdo principal

Pré PIX Transaction

No momento em que o pagador tiver a intenção de iniciar um pagamento, os dados da transação poderao ser avaliados previamente pelo nosso servidor. Deste modo, será possível realizar uma análise prévia do risco envolvido na transação, baseado naquele conjunto de dados.

Definição do Objeto de Pré Pix Transactions​

Request Body
{
    "id": "082373263",
    "transaction_direction": "received",
    "client": {
        "id": "123456",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "type": "natural_person",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "amount": 13725,
    "dict_key": {
        "key_type": "cpf",
        "key_value": "09991222669",
        "assignment_date": "2020-01-15T18:00:00-03:00"
    },
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "legal_person",
            "document_number": "07.487.735/0001-69",
            "name": "Gioconda Pizzaria e Rotisseria LTDA."
        },
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_account": {
        "participant": "60701190",
        "branch": "3675",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "natural_person",
            "document_number": "056.966.649-03",
            "name": "Francisco Oliveira Benedetti"
        },
        "account_type": "SLRY",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_statistics": {
        "person":{
            "settlements":{
                "d90":4,
                "m12":67,
                "m60":618
            },
            "application_frauds":{
                "d90":0,
                "m12":4,
                "m60":9
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "registered_accounts":0
        },
        "owner":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "registered_accounts":0
        },
        "key":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            }
        }
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.065.098",
        "session_id": "7839jdqd9a8wd9"
    },
    "event_date": "2019-12-11T11:37:15.12-03:00"
}

Uma transação deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status da transação representa a decisão retornada pelo modelo sobre aquela transação. Os seguintes status são utilizados na flag analysis_status:

  • automatically_approved
  • automatically_reproved
  • automatically_challenged
  • pending

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

statusdescrição
automatically_approvedRecomenda-se que esta transação seja aprovada.
automatically_reprovedRecomenda-se que esta transação seja reprovada.
automatically_challengedOs algoritmos da QI Tech recomendam que esta transação seja desafiado
pendingA transação está sendo processada.
nometipodescrição
idstringIdentificador do pagamento no sistema do cliente.
É essencial que este número seja único para cada processo de pagamento (obrigatório)
transaction_directionenumeradorTipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. (obrigatório)
clientclientObjeto que representa os dados do cliente, seja ele o pagador ou o recebedor. (obrigatório)
amountinteiroO valor do pagamento, em centavos- conforme descrição da seção "Padrões". (obrigatório)
pix_modalitystringTipo de transação cadastrada. Indica se representa uma transferência, um troco ou um saque.
dict_keydict_keyObjeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação.
face_recognition_keystringChave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
source_accountsource_accountObjeto que representa os dados da conta debitada. (obrigatório)
destination_accountdestination_accountObjeto que representa os dados da conta creditada. (obrigatório)
destination_statisticsdestination_statisticsObjeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN.
sourcesourceObjeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento
event_datedatetimeA data e hora de início da transação, com fuso horário. (obrigatório)

Existem os seguintes enumeradores para transaction_direction: sent e received.

Existem os seguintes enumeradores para pix_modality: transacation, change e withdraw.

Enviar uma Pré Transação​

Request Body
  {
    "id": "12345",
    ...
  }
Response Body
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum",
    "reason_desciption": "Descrição da regra"
  }

Para realizar a avaliação de uma pre transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint:

POST https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction

Fluxo de Desafio​

É possível, após a execução da análise, ter como decisão desafiar o usuário para realizar uma nova ação em sua plataforma. Esse fluxo pode ser utilizado para, por exemplo, solicitar um 2FA, como uma análise facial, para o usuário.

Passo-a-passo da execução do fluxo​

1. O Evento é submetido para análise, e retornará o status automatically_challenged.

Request Body
{
    "id": "082373263",
    ...
    "event_date": "2019-12-11T11:37:15.12-03:00"
}
Response Body
{
  "id": "082373263",
  "analysis_status": "automatically_challenge"
  ...
}

2. Após a primeira requisição de análise ter retornado um analysis_status de desafio, uma nova requisição pode ser enviada com o resultado do processo do cliente caso o mesmo tenha sido finalizado. Esta requisição deve ser feita no mesmo event_id da requisição anterior e o status atual deve ser obrigatoriamente automatically_challenged. Os possíveis status para essa atualização são:

  • approved_by_client
  • reproved_by_client

PATCH https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction/{event_id}

Request Body: Envio com informações adicionais
{
    "analysis_status": "approved_by_client"
}
Response Body
{
  "id": "082373263",
  "analysis_status": "approved_by_client"
  ...
}