Informações adicionais

Detalhes técnicos sobre campos da API de pagamentos.

Nesta seção apresentamos informações adicionais sobre alguns campos importantes da API de pagamentos e transações:

📘

A lista completa de campos e opções está na documentação dos documentação dos métodos da API.

Requisição

id

Existem 3 campos diferentes com o nome id. Embora parecidos, cada um tem uma função diferente na plataforma.

  • payment.id: Representa o código do pagamento. Deve ser informado na criação de um pagamento e usado na atualização posterior do mesmo pagamento. Normalmente este é um código interno que será usado para agrupar retentativas automáticas de transação. Se não for informado, um código será gerado pela plataforma.
  • transaction.id: Código opcional da transação. Representa uma tentativa de comunicação com uma instituição financeira. Você deve enviar um código interno do seu sistema sempre que possível. Caso contrário, envie uma concatenação do código do conector + código único gerado pelo conector (TID, NSU, etc). Por exemplo: 31231-9957812331231. Ainda assim, se não for possível gerar um código único, não envie o campo.
  • order.id: Código opcional do pedido (ou pedido, mensalidade, carrinho, etc). Este código será usado para rastrear retentativas realizadas em múltiplos pagamentos diferentes.

Entendemos que muitas vezes nem todas essas informações estão disponíveis e que uma solução natural é natural repetir o mesmo código duas ou até três vezes nos campos acima. Não recomendamos essa prática pois os campos são opcionais. Quando a informação não estiver disponível, evite enviar dados apenas para preencher o campo.

Se o mesmo código for enviado repetido em vários campos, poderão haver consequências na qualidade na análise. Por exemplo: quando order.id recebe o mesmo valor que payment.id, a plataforma irá reportar erroneamente que a quantidade de tentativas por compra é sempre 1. Nesse caso, a solução ideal é buscar algum identificador que represente o pedido (ou mensalidade, etc) em todos os pagamentos que o cliente (ou sistema) possa vir a realizar.

Em último caso, se não for possível obter uma informação confiável, não envie o campo opcional. Dessa forma, as análises não serão afetadas negativamente por dados que não representam a realidade.

status

Tanto o pagamento quanto a transação possuem o parâmetro status. A diferença entre eles é que o status do pagamento é obtido após o processamento de todas as transações. Por exemplo, se um pagamento gerou três transações recusadas e uma aprovada, o status final do pagamento será succeeded. Já o status de cada transação representa a resposta de cada tentativa de comunicação, se houver.

Status do pagamento

Os status possíveis para o pagamento são:

  • initiated: O pagamento foi iniciado, porém ainda não foi processado pelo conector (adquirente, subadquirente ou gateway). Este é o único status que permite análise antifraude.
  • succeeded: O pagamento foi aprovado pelo conector em ao menos uma das transações.
  • declined: O pagamento foi recusado pelo conector.
  • blocked: O pagamento foi bloqueado de acordo com sua decisão, seja pela pontuação da probabilidade de fraude ou pela análise do antifraude tradicional, se houver.
  • failed: Houve um erro ao efetuar a tentativa de transação. Utilize no caso de falhas de infraestrutura, configuração ou quando a causa do problema é desconhecida.

Os status succeeded e declined obrigam o envio do parâmetro transactions na mesma requisição. Já os status failed e blocked não obrigam, porém recomendamos enviar as transações quando houver alguma tentativa.

Status da transação

Os status possíveis para a transação são:

  • succeeded: A transação foi aprovada pelo conector com sucesso.
  • declined: A transação foi recusada pelo conector.
  • failed: Houve um erro ao efetuar a tentativa de transação. Utilize no caso de falhas de infraestrutura, configuração ou quando a causa do problema é desconhecida.

timestamp

A criação do pagamento permite o envio do campo timestamp. Este campo representa o horário em que a tentativa de pagamento foi iniciada e deve ser enviado no formato ISO 8601 sempre que possível. Exemplo: 2022-01-01T13:21:02.431-03:00.

Resposta

analyses

Quando um pagamento é criado com a opção analyze.bot_behaviour = true, a API irá retornar o resultado da detecção de bots no atributo analyses.bot_behaviour, contendo os seguintes campos:

  • action: recomendação de ação baseada na pontuação de risco (score) e na configuração do painel. Este campo pode retornar os seguintes valores:
    • allow: recomenda o processamento normal da transação.
    • challenge: recomenda verificações adicionais, se possível.
    • deny: recomenda o bloqueio do pagamento.
  • score: pontuação de 0 a 1 indicando a pontuação de risco do pagamento ter sido realizado através de um bot.

Recomendamos utilizar a recomendação do campo action para implementar a tomada de decisão ao invés de criar regras hard-coded baseadas no score. A sensibilidade da recomendação pode ser configurada no painel de administração.