Pular para o conteúdo principal

PIX Transaction

No momento em que o pagador iniciar ou receber um pagamento, os dados da transação deverão ser enviados para o nosso servidor. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados.

Definição do Objeto de Pix Transactions​

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

Uma transação 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 da transação representa a decisão retornada pelo modelo sobre aquela transação. Os seguintes status são utilizados na flag analysis_status:

  • automatically_approved
  • automatically_reproved
  • in_manual_analysis
  • pending

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

statusdescrição
automatically_approvedRecomenda-se que esta transação seja aprovada.
automatically_reprovedRecomenda-se que esta transação seja reprovada.
approved_by_timeA transação foi aprovada por expiração de tempo de análise manual
reproved_by_timeA transação foi aprovada por expiração de tempo de análise manual
in_manual_analysisRecomenda-se que a transação seja analisada manualmente por um analista.
pendingA transação está sendo processada.
nometipodescrição
transaction_directionenumeradorTipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. (obrigatório)
idstringIdentificador do pagamento no sistema do cliente.
É essencial que este número seja único para cada processo de pagamento (obrigatório)
clientclientObjeto que representa os dados do cliente, seja ele o pagador ou o recebedor. (obrigatório)
amountinteiroO valor do pagamento, em centavos- conforme descrição da seção "Padrões". (obrigatório)
pix_modalitystringTipo de transação cadastrada. Indica se representa uma transferência, um troco ou um saque.
transaction_datedatetimeA data e hora de início da transação, com fuso horário. (obrigatório)
dict_keydict_keyObjeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação.
capture_methodenumeradorMétodo utilizado para iniciação do pagamento, se foi via QR Code estático ou dinâmico, via preenchimento de dados ou via chave da DICT. (obrigatório)
face_recognition_keystringChave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_keystringChave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
source_accountsource_accountObjeto que representa os dados da conta debitada. (obrigatório)
destination_accountdestination_accountObjeto que representa os dados da conta creditada. (obrigatório)
destination_statisticsdestination_statisticsObjeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN. (obrigatório)
sourcesourceObjeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento

Existem os seguintes enumeradores para transaction_direction: sent e received.

Existem os seguintes enumeradores para pix_modality: transacation, change e withdraw.

Existem os seguintes enumeradores para capture_method: static_qr_code, dynamic_qr_code, offline_qr_code, typed.

Enviar uma Transação​

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

Para realizar a avaliação de uma transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint:

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

Recuperar uma Transação​

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

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

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

Onde transaction_id é o identificador da transação que nos foi enviado no momento do cadastro, no campo "id".

Atualizar uma Transação​

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

Após uma transação ser criada e analisada, ela deve ser enviada ao BCB para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transação quando essa for enviada ao BCB, através do endpoint:

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

Deste modo, garante-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB.

Transação não efetivada​

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

Caso uma transação, por qualquer motivo, não tenha sido efetivada (i.e.: Saldo debitado da conta de origem e creditado na conta de destino), a transação pode ser atualizada para o status cancelled, com a razão do cancelamento para que seja possível identificar perfis de fraude relacionados a transação não efetivadas. O status cancelled só pode ser utilizado em transações que ainda possuem o status created, uma vez que o status sent é utilizado nos casos em que a transação foi evetivada.

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

As seguintes reasons são atualmente aceitas pela API, caso você veja a necessidade de enquadrar o motivo do cancelamento em outra reason, por favor, entre em contato com suporte.caas@qitech.com.br.

reasondescrição
insufficient_balanceO cliente não possui saldo na conta para realizar a transação
fraud_preventionA transação foi cancelada pois não foi aprovada no sistema antifraude
system_blockAlgum bloqueio de sistema não permitiu a execução da transação, por exemplo conta cancelada/inativa ou limite alcançado
invalid_destinationA instituição contraparte não aceitou a transação pois a conta de destino não existe
refused_by_counterpartA instituição contraparte rejeitou a transação
system_errorA transação foi cancelada pois houve um erro no sistema da própria instituição
invalid_authenticationA transação foi cancelada pois o cliente não passou em algum fluxo de autenticação