Pre-PIX Transaction

The moment a payer intends to initiate a payment, the transaction data can be previously evaluated by our server. This allows for a preliminary risk analysis based on that specific dataset.

Pre-Pix Transaction Object Definition

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"
}

A transaction must be sent to the API before being forwarded to the processing system in order to perform a preliminary fraud validation.

The transaction status represents the decision returned by the model for that transaction. The following statuses are used in the analysis_status flag:

automatically_approved
automatically_reproved
automatically_challenged
pending

The meanings of each decision returned in the analysis_status flag are listed below:

status	description
automatically_approved	It is recommended that this transaction be approved.
automatically_reproved	It is recommended that this transaction be rejected.
automatically_challenged	QI Tech's algorithms recommend that this transaction be challenged.
pending	The transaction is currently being processed.

name	type	description
id	string	Payment identifier in the client's system. It is essential that this number is unique for each payment process (required)
transaction_direction	enumerador	Type of registered transaction. Defines whether the client is receiving or sending money. (required)
client	client	Object representing client data, whether they are the payer or the receiver. (required)
amount	inteiro	The payment amount in cents — as described in the "Standards" section. (required)
pix_modality	string	Type of registered transaction. Indicates if it represents a transfer, change, or withdrawal.
dict_key	dict_key	Object representing the DICT link key data used by the client in the transaction.
face_recognition_key	string	Facial recognition key, if facial recognition was performed via our API.
source_account	source_account	Object representing the data of the debited account. (required)
destination_account	destination_account	Object representing the data of the credited account. (required)
destination_statistics	destination_statistics	Object representing the transaction and fraud history of the credited account from the Central Bank's (BACEN) DICT API.
source	source	Source object describing information from the application used to send the payment.
event_date	datetime	The start date and time of the transaction, including timezone. (required)

The following enumerators are available for transaction_direction: sent and received.

The following enumerators are available for pix_modality: transacation, change and withdraw.

Submit a Pre-Transaction

Request Body

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

Response Body

  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum",
    "reason_desciption": "description da regra"
  }

To perform a pre-transaction evaluation, simply send a Transaction type object to the following endpoint:

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

Challenge Flow

After the analysis is executed, it is possible for the decision to be a "challenge," requiring the user to perform a new action on your platform. This flow can be used, for example, to request 2FA, such as facial analysis, from the user.

Execution Flow Step-by-Step

1. The event is submitted for analysis and will return the 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. After the initial analysis request returns a challenge analysis_status, a new request can be sent with the result of the client's process once finalized. This request must use the same event_id as the previous request, and the current status must be automatically_challenged. The possible statuses for this update are:

approved_by_client
reproved_by_client

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

Request Body: Submission with additional information

{
    "analysis_status": "approved_by_client"
}

Response Body

{
  "id": "082373263",
  "analysis_status": "approved_by_client"
  ...
}