Shared Objects
A significant portion of data is shared among different account events. The definitions of these objects can be easily located below.
Client Object
Request Body
{
"id": "123456",
"type": "natural_person",
"document_number": "023.456.789-01",
"name": "John Payer",
"email": "john@payer.com",
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "998861708",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
}
Object representing the account holder's data.
| name | type | description |
|---|---|---|
| type | enum (mandatory) | Client type: "natural_person" or "legal_person" |
| document_number | string (mandatory) | Document number, in accordance with the standardization section. |
| name | string (mandatory) | Client name. |
| string | Client email. | |
| address | address | Client address data. |
| phone | phone | Client phone data. |
| sales_channel | enum (mandatory) | Channel through which the client registered. |
| segment | string (mandatory) | Client segment within the institution (e.g., premium, gold). |
The following enumerators exist for phone type: inbound_sales, app, website, call_center, and branch.
Address Object
Request Body
{
"street": "Rua do Teste",
"number": "111",
"neighbourhood": "Bairro do Exemplo",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "Térreo",
"postal_code": "00000-000",
"country": "BRA"
}
The address object is used to represent addresses throughout the API. Addresses within Brazilian territory are represented as follows:
| name | type | description |
|---|---|---|
| street | string (mandatory) | Street name, including the public place type, avoiding abbreviations if possible. |
| number | string (mandatory) | Property number, including letters if applicable. |
| neighbourhood | string (mandatory) | Neighborhood, without abbreviations. e.g.: Santa Felicidade |
| city | string (mandatory) | Full city name, without abbreviations. |
| uf | string (mandatory) | The federative unit (state), with two uppercase letters. e.g.: SP |
| complement | string | Any supplements to locate the property. e.g.: Apartamento 101, Conjunto 12 |
| postal_code | string (mandatory) | The locality's postal code, including the hyphen. |
| country | string (mandatory) | ISO 3166-1 alpha-3 code of the address country. |
For addresses where the country is not Brazil ("BRA"), the postal_code and federative unit may be filled in freely.
Phone Object
Request Body
{
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile"
}
A phone object represents a telephone number, inside or outside Brazil, and its classification. For this, the fields are:
| name | type | description |
|---|---|---|
| international_dial_code | string (mandatory) | International dialing code, without zero or +, numbers only. |
| area_code | string (mandatory) | Area code, without zero, numbers only. |
| number | string (mandatory) | Phone number, without the hyphen. |
| type | enum (mandatory) | Number type: mobile, residential, commercial, etc. |
The following enumerators exist for phone type: residential, commercial, and mobile.
Account Object
Request Body
{
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
}
Object representing an account's data.
| name | type | description |
|---|---|---|
| participant | string (mandatory) | ISPB of the institution holding the account. |
| branch | string (mandatory) | Account Branch. |
| account_number | string (mandatory) | Account Number without the digit. |
| account_digit | string (mandatory) | Account digit. |
| account_type | enum (mandatory) | Source account type, possible values: "CACC", "SLRY", and "SVGS". |
| opening_date | datetime | Account opening date. |
Source Object
Request Body
{
"channel": "app",
"platform": "android",
"ip":"255.201.26.1",
"session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
}
The source object represents the set of information regarding the platform used by the user to perform the operation. The fields are:
| name | type | description |
|---|---|---|
| channel | string | Channel used by the user to perform the operation, e.g., internet banking, app. |
| platform | string | Platform used by the application. |
| ip | string | IP collected from the device. |
| session_id | string | Unique session identifier, used to cross-reference the Device Scan with the event in question. |
Dict Key Object
Request Body
{
"key_type": "cpf",
"key_value": "09991222669",
"assignment_date": "2020-01-15T18:00:00-03:00"
}
The dict_key object is used to represent the client's DICT link key data, whether they are the receiver or the payer of the transaction. The fields of this object are:
| name | type | description |
|---|---|---|
| key_type | string (mandatory) | Enumerator containing the DICT link key type. |
| key_value | string | Contains the link key registered in DICT. |
| assignment_date | datetime | Date the link key was registered in DICT. |
The enumerators for the key_type field are the same as those defined in the DICT API: cpf, cnpj, email, phone, and evp.
Destination Statistics Object
Request Body
{
"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
}
}
}
To evaluate the fraud risk of a transaction with greater precision, it is necessary to provide the transactional and fraud history of the payee via the Destination Statistics object. Such data can be obtained by querying the payee's link key in the DICT database. The Central Bank of Brazil (BACEN) requires that this data be used in the transaction fraud evaluation.
| name | type | description |
|---|---|---|
| account | account (mandatory) | Object containing the transactional and fraud history of the payee's account. |
| owner | owner (mandatory) | Object containing the transactional and fraud history associated with the payee's document. |
| key | key (mandatory) | Object containing the transactional and fraud history associated with the key provided by the payee. |
Where each of the objects defined above possesses the same fields:
| name | type | description |
|---|---|---|
| settlements | settlements (mandatory) | Object containing the transactional history. |
| rejected | rejected (optional) | Object containing the history of rejected operations. |
| reported_frauds | reported_frauds (mandatory) | Object containing the history of fraud reports. |
| reported_aml_cft | reported_aml_cft (optional) | Object containing the history of AML/CFT reports. |
| confirmed_frauds | confirmed_frauds (mandatory) | Object containing the history of confirmed fraud reports. |
| confirmed_aml_cft | confirmed_aml_cft (optional) | Object containing the history of confirmed AML/CFT reports. |
Where each of these objects contains the fields d3, d30, and m6, containing the number of occurrences in the last 3 days, 30 days, and 6 months, which are mandatory fields, respectively. Just as defined by the BCB DICT API.