Pular para o conteúdo principal

Saques

No momento em que um usuário efetuar um saque, os dados do saque deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados.

Definição do Objeto de Saque​

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

Um saque deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status do saque representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag analysis_status:

  • automatically_approved
  • automatically_reproved

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

statusdescrição
automatically_approvedRecomenda-se que este saque seja aprovado.
automatically_reprovedRecomenda-se que este saque seja reprovado.
nometipodescrição
idstringIdentificador do saque no sistema do cliente.
É essencial que este número seja único para cada saque
amountinteiroValor do saque em centavos - conforme descrição da seção "Padrões".
withdrawal_datedatetimeData e hora da realização do saque - conforme descrição da seção "Padrões"
source_accountaccountObjeto que determina a conta de origem do recurso a ser sacado
clientclientObjeto com os dados do cliente detentor da conta de origem
terminalterminalObjeto com os dados do terminal onde o saque está sendo realizado
authenticationauthenticationObjeto com as informações de autenticação

Objetos do Saque​

Objeto Terminal​

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

Objeto que representa o terminal que foi utilizado para o saque.

nometipodescrição
idstringIdentificador do terminal no sistema do cliente
latitudenumberLatitude, em graus, da localização do terminal
longitudenumberLongitude, em graus, da localização do terminal
addressaddressEndereço do terminal
typeenumTipo do terminal, possíveis valores: "atm", "counter"

Objeto Authentication​

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

Objeto que define os parâmetros da autenticação utilizada no momento do saque.

nometipodescrição
used_passwordbooleanDetermina se o usuário utilizou senha
used_cardbooleanDetermina se o usuário está com o cartão presente na autenticação
used_card_chip_and_pinbooleanDetermina se o usuário utilizou o chip e senha do cartão
used_card_magnetic_stripebooleanDetermina se o usuário utilizou a tarja magnética do cartão
used_fingerprintbooleanDetermina se o usuário utilizou fingerprint
typed_account_numberbooleanDetermina se o usuário digitou os dados da conta

Enviar um Saque​

Request Body
  {
    "id": "12345",
    ...
  }
Response Body
  {
    "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }

Para realizar a avaliação de um pagamento de conta, basta enviar um objeto do tipo withdrawal ao seguinte endpoint:

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

Recuperar um Saque​

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

Para recuperar os dados de um saque, basta enviar uma requisição ao seguinte endpoint:

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

Onde withdrawal_id é o identificador da transação no sistema do cliente utilizado no envio do saque.

Atualizar um saque​

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

Após um saque ser criada e analisada, o dinheiro será disponibilizado ao usuário. Este processo pode ser interrompido por alguma outra regra de negócio. Deste modo, é necessário que seja informada a atualizações de status do saque quando este for finalizado, através do endpoint:

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

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os saques que estejam realmente sucetíveis a fraude.