PIX Transaction

At the moment a payer initiates or receives a payment, the transaction data must be sent to our server. This enables a risk analysis of the transaction based on that dataset.

PIX Transaction Object Definition

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"
        },
        "email": "mailto@qitech.com.br",
        "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
            },
            "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"
    }
}

A transaction must be sent to the API for prior fraud validation before being forwarded to the processing system.

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

automatically_approved
automatically_reproved
in_manual_analysis
pending

Below are the meanings of each decision returned in the analysis_status flag:

status	description
automatically_approved	It is recommended that this transaction be approved.
automatically_reproved	It is recommended that this transaction be reproved.
approved_by_time	The transaction was approved due to manual analysis time expiration.
reproved_by_time	The transaction was reproved due to manual analysis time expiration.
in_manual_analysis	It is recommended that the transaction be analyzed manually by an analyst.
pending	The transaction is being processed.

name	type	description
transaction_direction	enumerator	Registered transaction type. Defines whether the client is receiving or sending money. (mandatory)
id	string	Payment identifier in the client's system. It is essential that this number is unique for each payment process (mandatory)
client	client	Object representing the client's data, whether they are the payer or the receiver. (mandatory)
amount	integer	The payment amount in cents - as described in the "Standards" section. (mandatory)
pix_modality	string	Registered transaction type. Indicates if it represents a transfer, change (troco), or withdrawal.
transaction_date	datetime	The transaction start date and time, with time zone. (mandatory)
dict_key	dict_key	Object representing the DICT link key data used by the client in the transaction.
capture_method	enumerator	Method used for payment initiation, whether via static or dynamic QR Code, data entry, or DICT key. (mandatory)
face_recognition_key	string	Facial recognition key, if facial recognition was performed by our facial recognition API.
validation_key	string	Validation key, if any client validation test was performed in our validation API.
source_account	source_account	Object representing the debited account data. (mandatory)
destination_account	destination_account	Object representing the credited account data. (mandatory)
destination_statistics	destination_statistics	Object representing the transaction and fraud history of the credited account originating from the BACEN DICT API. (mandatory)
source	source	Source type object describing information coming from the application used for sending the payment.

The following enumerators exist for transaction_direction: sent and received.

The following enumerators exist for pix_modality: transaction, change, and withdraw.

The following enumerators exist for capture_method: static_qr_code, dynamic_qr_code, offline_qr_code, typed.

Send a Transaction

Request Body

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

Response Body

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

To perform the evaluation of a transaction, simply send a Transaction object to the following endpoint:

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

Retrieve a Transaction

Response Body

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

To retrieve data from a transaction, simply send a request to the following endpoint:

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

Where transaction_id is the transaction identifier sent to us at the time of its registration, in the "id" field.

Update a Transaction

Request Body

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

After a transaction is created and analyzed, it must be sent to the BCB (Central Bank) for processing. Therefore, it is necessary to report transaction status updates when it is sent to the BCB via the endpoint:

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

This ensures that our database is updated and always consistent with the BCB database.

Unsuccessful Transaction

Request Body

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

If a transaction, for any reason, has not been completed (i.e., balance debited from the source account and credited to the destination account), the transaction can be updated to the cancelled status, with the cancellation reason, so that it is possible to identify fraud profiles related to incomplete transactions. The cancelled status can only be used on transactions that still have the created status, since the sent status is used in cases where the transaction was completed.

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

The following reasons are currently accepted by the API. If you see the need to frame the cancellation reason in another reason, please contact suporte.caas@qitech.com.br.

reason	description
insufficient_balance	The client does not have sufficient account balance to perform the transaction.
fraud_prevention	The transaction was cancelled because it was not approved in the antifraud system.
system_block	A system block prevented transaction execution, for example, cancelled/inactive account or limit reached.
invalid_destination	The counterparty institution did not accept the transaction because the destination account does not exist.
refused_by_counterpart	The counterparty institution rejected the transaction.
system_error	The transaction was cancelled because there was an error in the institution's own system.
invalid_authentication	The transaction was cancelled because the client failed an authentication flow.

PIX Transaction Object Definition​

Send a Transaction​

Retrieve a Transaction​

Update a Transaction​

Unsuccessful Transaction​

PIX Transaction Object Definition

Send a Transaction

Retrieve a Transaction

Update a Transaction

Unsuccessful Transaction