Withdrawals

At the moment a user performs a withdrawal, the withdrawal data must be sent to QI Tech. This enables a risk analysis of the operation based on that dataset.

Withdrawal Object Definition

Request Body

{
    "id": "082373263",
    "amount": 12979,
    "withdrawal_date": "2020-10-07T15:06:25-03:00",
    "service_description": "SAQUE EM CAIXA 24H",
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "client": {
        "id": "182373263",
        "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é"
    },
    "terminal": {
        "id": "1234566",
        "latitude": -45.2753548,
        "longitude": -15.24587,
        "address": { 
            "street": "Av. Eng. Luis Carlos Berrini",
            "number": "105",
            "neighbourhood": "Brooklin",
            "city": "São Paulo",
            "uf": "SP",
            "complement": "Cj 303",
            "postal_code": "04501-140"
        },
        "type": "atm"
    },
    "authentication": {
        "used_password": true,
        "used_card": true,
        "used_fingerprint": true,
        "typed_account_number": false
    }
}

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

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

• automatically_approved
• automatically_reproved

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

status	description
automatically_approved	It is recommended that this withdrawal be approved.
automatically_reproved	It is recommended that this withdrawal be reproved.

name	type	description
id	string	Withdrawal identifier in the client's system. It is essential that this number is unique for each withdrawal
amount	integer	Withdrawal amount in cents - as described in the "Standards" section.
withdrawal_date	datetime	Date and time of the withdrawal execution - as described in the "Standards" section.
source_account	account	Object determining the source account of the funds to be withdrawn.
client	client	Object containing the data of the client holding the source account.
terminal	terminal	Object containing the data of the terminal where the withdrawal is being performed.
authentication	authentication	Object containing the authentication information.

Withdrawal Objects

Terminal Object

Request Body

{
    "id": "1234566",
    "latitude": -45.2753548,
    "longitude": -15.24587,
    "address": { 
        "street": "Av. Eng. Luis Carlos Berrini",
        "number": "105",
        "neighbourhood": "Brooklin",
        "city": "São Paulo",
        "uf": "SP",
        "complement": "Cj 303",
        "postal_code": "04501-140"
    },
    "type": "atm"
}

Object representing the terminal that was used for the withdrawal.

name	type	description
id	string	Terminal identifier in the client's system.
latitude	number	Latitude, in degrees, of the terminal's location.
longitude	number	Longitude, in degrees, of the terminal's location.
address	address	Terminal address.
type	enum	Terminal type, possible values: "atm", "counter".

Authentication Object

Request Body

{
    "used_password": true,
    "used_card": true,
    "used_fingerprint": true,
    "typed_account_number": false
}

Object defining the authentication parameters used at the time of withdrawal.

name	type	description
used_password	boolean	Determines if the user used a password.
used_card	boolean	Determines if the user has the card present during authentication.
used_card_chip_and_pin	boolean	Determines if the user used the card's chip and PIN.
used_card_magnetic_stripe	boolean	Determines if the user used the card's magnetic stripe.
used_fingerprint	boolean	Determines if the user used a fingerprint.
typed_account_number	boolean	Determines if the user typed the account data.

Send a Withdrawal

Request Body

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

Response Body

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

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

POST https://api.caas.qitech.app/withdrawal/withdrawal

Retrieve a Withdrawal

Request Body

  {
    "id": "082373263",
    "amount": 12979,
    ...
  }

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

GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}

Where withdrawal_id is the transaction identifier in the client's system used when sending the withdrawal.

Update a Withdrawal

Request Body

  {
    "withdrawal_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }

Response Body

  {
    "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "withdrawal_status": "completed"
  }

After a withdrawal is created and analyzed, the money will be made available to the user. This process may be interrupted by some other business rule. Thus, it is necessary to report withdrawal status updates when it is finalized, via the endpoint:

PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}

This ensures that our database remains updated, allowing us to accurately identify withdrawals that are genuinely susceptible to fraud.