PIX Transaction

No momento em que o pagador iniciar ou receber um pagamento, os dados da transação deverão ser enviados para o nosso servidor. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados.

Definição do Objeto de Pix Transactions

Payload para API DICT V1

Request Body

{
    "transaction_direction": "received",
    "id": "082373263",
    "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,
    "transaction_date": "2020-10-07T15:06:25-03:00",
    "dict_key": {
        "key_type": "cpf",
        "key_value": "09991222669",
        "assignment_date": "2020-01-15T18:00:00-03:00"
    },
    "capture_method": "static_qr_code",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "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": {
        "account":{
            "settlements":{
                "d3":4,
                "d30":67,
                "m6":618
            },
            "rejected":{
                "d3":4,
                "d30":67,
                "m6":618
            },
            "reported_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "reported_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            }
        },
        "owner":{
            "settlements":{
                "d3":6,
                "d30":88,
                "m6":996
            },
            "rejected":{
                "d3":4,
                "d30":67,
                "m6":618
            },
            "reported_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "reported_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            }
        },
        "key":{
            "settlements":{
                "d3":3,
                "d30":51,
                "m6":312
            },
            "rejected":{
                "d3":4,
                "d30":67,
                "m6":618
            },
            "reported_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "reported_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_frauds":{
                "d3":0,
                "d30":0,
                "m6":0
            },
            "confirmed_aml_cft":{
                "d3":0,
                "d30":0,
                "m6":0
            }
        }
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.065.098",
        "session_id": "7839jdqd9a8wd9"
    }
}

Payload para API DICT V2

Request Body

{
    "transaction_direction": "received",
    "id": "082373263",
    "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,
    "transaction_date": "2020-10-07T15:06:25-03:00",
    "dict_key": {
        "key_type": "cpf",
        "key_value": "09991222669",
        "assignment_date": "2020-01-15T18:00:00-03:00"
    },
    "capture_method": "static_qr_code",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "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
            },
            "total_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
            },
            "total_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
            },
            "total_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"
    }
}

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
• in_manual_analysis
• pending

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

status	descrição
automatically_approved	Recomenda-se que esta transação seja aprovada.
automatically_reproved	Recomenda-se que esta transação seja reprovada.
approved_by_time	A transação foi aprovada por expiração de tempo de análise manual
reproved_by_time	A transação foi aprovada por expiração de tempo de análise manual
in_manual_analysis	Recomenda-se que a transação seja analisada manualmente por um analista.
pending	A transação está sendo processada.

nome	tipo	descrição
transaction_direction	enumerador	Tipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. (obrigatório)
id	string	Identificador do pagamento no sistema do cliente. É essencial que este número seja único para cada processo de pagamento (obrigatório)
client	client	Objeto que representa os dados do cliente, seja ele o pagador ou o recebedor. (obrigatório)
amount	inteiro	O valor do pagamento, em centavos- conforme descrição da seção "Padrões". (obrigatório)
original_amount	inteiro	O valor do pagamento, em centavos- modalidade PIX Saque (igual a 0) e PIX Troco (valor do produto/serviço, diferente de 0).
pss_ispb	string	ISPB do PSS (Prestador de Serviço de Saque)- modalidade PIX Saque e PIX Troco.
agent_modality	string	Objeto indica a modalidade do agente por meio da qual se dá a prestação do serviço de saque, quais sejam via estabelecimento comercial (AGTEC), outra espécie de pessoa jurídica (AGTOT) ou prestador de serviço de saque (AGPSS).
amount_modification_policy	string	Objeto indica a modalidade de alteração aplicada para a cobrança em questão (fixo ou modificável).
withdrawal_amount	inteiro	O valor do saque, em centavos- modalidade PIX Saque.
change_amount	inteiro	O valor do troco sacado, em centavos- modalidade PIX Troco.
transaction_date	datetime	A data e hora de início da transação, com fuso horário. (obrigatório)
dict_key	dict_key	Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação.
capture_method	enumerador	Método utilizado para iniciação do pagamento, se foi via QR Code estático ou dinâmico, via preenchimento de dados ou via chave da DICT. (obrigatório)
face_recognition_key	string	Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_key	string	Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
source_account	source_account	Objeto que representa os dados da conta debitada. (obrigatório)
destination_account	destination_account	Objeto que representa os dados da conta creditada. (obrigatório)
destination_statistics	destination_statistics	Objeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN. (obrigatório)
source	source	Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento

Existem os seguintes enumeradores para transaction_direction: sent e received.

Existem os seguintes enumeradores para capture_method: static_qr_code, dynamic_qr_code, offline_qr_code, typed

Enviar uma Transação

Request Body

  {
    "id": "12345",
    ...
  }

Response Body

  {
    "transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }

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

POST https://api.caas.qitech.app/pix/transaction

Recuperar uma Transação

Response Body

  {
    "transaction_direction": "received",
    "id": "082373263",
    ...
  }

Para recuperar os dados de uma transação, basta enviar uma requisição ao seguinte endpoint:

GET https://api.caas.qitech.app/pix/transaction/{transaction_id}

Onde transaction_id é o identificador da transação que nos foi enviado no momento do cadastro, no campo "id".

Atualizar uma Transação

Request Body

  {
    "transaction_status": "sent",
    "event_date": "2020-10-07T15:06:25-03:00"
  }

Após uma transação ser criada e analisada, ela deve ser enviada ao BCB para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transação quando essa for enviada ao BCB, através do endpoint:

PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}

Deste modo, garante-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB.

Transação não efetivada

Request Body

  {
    "transaction_status": "cancelled",
    "reason": "refused_by_counterpart",
    "event_date": "2020-10-07T15:06:25-03:00"
  }

Caso uma transação, por qualquer motivo, não tenha sido efetivada (i.e.: Saldo debitado da conta de origem e creditado na conta de destino), a transação pode ser atualizada para o status cancelled, com a razão do cancelamento para que seja possível identificar perfis de fraude relacionados a transação não efetivadas. O status cancelled só pode ser utilizado em transações que ainda possuem o status created, uma vez que o status sent é utilizado nos casos em que a transação foi evetivada.

PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}

As seguintes reasons são atualmente aceitas pela API, caso você veja a necessidade de enquadrar o motivo do cancelamento em outra reason, por favor, entre em contato com suporte.caas@qitech.com.br.

reason	descrição
insufficient_balance	O cliente não possui saldo na conta para realizar a transação
fraud_prevention	A transação foi cancelada pois não foi aprovada no sistema antifraude
system_block	Algum bloqueio de sistema não permitiu a execução da transação, por exemplo conta cancelada/inativa ou limite alcançado
invalid_destination	A instituição contraparte não aceitou a transação pois a conta de destino não existe
refused_by_counterpart	A instituição contraparte rejeitou a transação
system_error	A transação foi cancelada pois houve um erro no sistema da própria instituição
invalid_authentication	A transação foi cancelada pois o cliente não passou em algum fluxo de autenticação