PIX Dict Operation
At the moment a user initiates a change in DICT, the data must be sent to our server so that we can perform an analysis of the risk involved in that dataset.
Dict Operation Object Definition
Request Body
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
"dict_key": {
"key_type": "phone",
"key_value": "16981610077",
"assignment_date": "2020-01-15T18:00:00-03:00"
},
"dict_operation_direction": "claimer",
"dict_operation_reason": "user_requested",
"dict_operation_creation_date": "2020-10-14T18:00:00-03:00",
"dict_operation_type": "claim_portability",
"client": {
"id": "123456",
"document_number": "099.912.226-69",
"name": "João Jorge da Silva",
"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": "65",
"number": "988961210",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"source_account": {
"participant": "04184779",
"branch": "0001",
"account_number": "1122",
"account_digit": "6",
"owner": {
"type": "legal_person",
"document_number": "94.948.708/0001-12",
"name": "Irmão Soares Ferragista LTDA."
},
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_account": {
"participant": "00000000",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "natural_person",
"document_number": "099.912.226-69",
"name": "João Jorge da Silva"
},
"account_type": "SLRY",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_statistics": {
"account":{
"settlements":{
"d3":12,
"d30":65,
"m6":344
},
"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":4,
"d30":12,
"m6":88
},
"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":1,
"d30":6,
"m6":12
},
"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-98",
"session_id": "7839jdqd9a8wd9"
}
}
A Dict Operation must be submitted to the API for preliminary registration fraud validation before being forwarded to the BCB processing system.
The analysis status of the Dict Operation represents the decision returned by the model regarding that operation. The following statuses are used in the analysis_status flag:
automatically_approvedautomatically_reprovedin_manual_analysispending
Below are the meanings of each decision returned in the analysis_status flag:
| status | description |
|---|---|
| automatically_approved | It is recommended that this operation be approved. |
| automatically_reproved | It is recommended that this operation be reproved. |
| in_manual_analysis | It is recommended that the operation be analyzed manually by an analyst. |
| pending | The operation is being processed. |
| name | type | description |
|---|---|---|
| id | string | Operation identifier in the client's system. It is essential that this number is unique for each authorization process |
| client | client | Object representing the client's data, whether they are the donor or the claimer. |
| transaction_date | datetime | The transaction start date and time, with time zone. |
| dict_key | dict_key | Object representing the DICT link key data used by the client in the transaction. |
| dict_key_type | enumerator | DICT link key type. |
| dict_operation_direction | enumerator | Operation direction in DICT, i.e., whether a key is being donated or claimed. |
| dict_operation_reason | enumerador | The reason why the Dict Operation is being performed. |
| dict_operation_creation_date | datetime | Date of the operation in DICT. |
| dict_operation_type | enumerador | Type of operation in DICT. |
| source_account | source_account | Object representing the data of the account that is donating the link key. |
| destination_account | destination_account | Object representing the data of the account that is receiving the link key. |
| destination_statistics | destination_statistics | Object representing the transaction and fraud history of the account receiving the link key. |
| source | source | Source type object describing the information coming from the application used to send the registration. |
The dict_key_type field accepts the same enumerators defined in the DICT API: cpf, cnpj, email, phone, and evp.
The dict_operation_direction field accepts the enumerators: donor and claimer.
The dict_operation_type field accepts the enumerators registration, claim_ownership, and claim_portability.
These being all types of DICT operations defined by the BCB.
Send a Dict Operation
Request Body
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
...
}
Response Body
{
"dict_operation_key": "7f85e162-5a7d-41fa-a578-69df6f3df958",
"status": "automatically_approved"
}
To perform the evaluation of an operation, simply send a Dict Operation object to the following endpoint:
POST https://api.caas.qitech.app/pix/dict_operation
Retrieve a Dict Operation
Response Body
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
...
}
To retrieve a Dict Operation, simply send a request to the following endpoint:
GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}
Where dict_operation_id is the operation identifier sent to us at the time of its registration, in the "id" field.
The Dict Operation object associated with the provided key will then be returned.
Update a Dict Operation
Request Body
{
"dict_operation_status": "cancelled_by_client",
"reason": "user_requested",
"event_date": "2020-10-07T15:06:25-03:00"
}
A Dict Operation goes through several phases with the BCB before completion. Thus, it is necessary to report all operation status updates via the endpoint:
PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}
This ensures that our database is updated and always consistent with the BCB database.
Some operations in DICT require that the reason for the operation be submitted along with the data. For these cases, it is necessary to provide the reason field in the submission object, containing the same enumerator provided to the BCB system. These are:
| enumerator | description |
|---|---|
| user_requested | The operation was requested by the client. |
| account_closure | The operation was initiated due to the client's account closure. |
| branch_transfer | The operation was requested due to the client's branch change. |
| entry_inactivity | The operation was requested due to inactivity in the client's account. |
| reconciliation | The operation was requested following a reconciliation process. |
| default_operation | The operation was requested by a default action of the participant. |
| fraud | The operation was requested due to fraud linked to the client's account. |
The phases of a DICT operation accepted by the dict_operation_status field are:
| enumerator | description |
|---|---|
| created | The dict_operation was created but has not yet been analyzed. |
| reproved | The dict_operation was reproved in the analysis and will not be sent to the BCB. |
| waiting_resolution | The dict_operation was sent to the BCB and is awaiting resolution. |
| cancelled_by_client | The dict_operation was cancelled by the client. |
| cancelled_by_counterpart | The dict_operation was cancelled by the other party of the operation. |
| confirmed | The dict_operation was confirmed by the other party of the operation. |
| completed | The dict_operation was completed and added to the BCB database. |