🛡️ Antifraude

📋 Visão Geral

O módulo de Antifraude permite enviar pagamentos de pedido para análise em uma integração antifraude configurada na loja e consultar o resultado dessa análise a qualquer momento.

O envio manual é utilizado quando a análise antifraude não é disparada automaticamente no checkout — por exemplo, em reprocessamentos ou fluxos de pagamento que exigem revisão explícita. Cada operação aceita até 100 pagamentos por requisição.

Além dos endpoints administrativos, a plataforma suporta atualização automática de status via webhook, permitindo que a integração antifraude notifique a loja sobre mudanças no resultado da análise sem intervenção manual.

🔄 Entidades Envolvidas

Cada análise antifraude está vinculada a um pagamento de pedido (OrderPayment) e a uma credencial antifraude (AntiFraudCredential). A credencial agrupa as chaves de acesso à integradora e define as políticas comerciais (tradePolicies) às quais ela se aplica.

Quando nenhuma credencial é informada explicitamente no envio, a plataforma utiliza a credencial padrão associada à política comercial do pedido.

O resultado de cada análise é representado por um status antifraude — os valores possíveis são approved, reproved e pending. A consulta retorna adicionalmente o score de risco (antiFraudScore) fornecido pela integradora, quando disponível.

📌 Notas e Considerações

• O envio manual registra a requisição com o tipo manual, distinguindo-o das análises disparadas automaticamente pelo checkout.
• Operações de envio exigem os escopos TRANSACTIONS_READ e ORDER_WRITE; a consulta exige apenas TRANSACTIONS_READ.
• Erros por pagamento são retornados no campo error de cada item da resposta — o HTTP permanece 200 mesmo quando ocorrem falhas individuais.
• A atualização de status via webhook é processada pela plataforma de forma assíncrona, sem necessidade de nova chamada aos endpoints administrativos.

🔍 Consulta de Antifraude

📋 Descrição

Endpoint responsável por consultar o status da análise antifraude de um ou mais pagamentos de pedido junto à integração antifraude configurada na loja, retornando o antiFraudStatus e o antiFraudScore de cada pagamento.

A consulta não é apenas uma leitura local — ela aciona a integradora e sincroniza o resultado no registro do pagamento (anti_fraud_status). A operação também registra um log de pagamento com origem ANTI_FRAUD, permitindo rastreabilidade da consulta.

Dependendo da configuração da credencial antifraude, a consulta pode disparar ações automáticas sobre o pagamento: se capture-on-approval estiver ativo, pagamentos aprovados são capturados automaticamente; se cancel-on-failure estiver ativo, pagamentos reprovados são cancelados sem intervenção manual.

O pagamento deve ter sido previamente enviado ao antifraude para que a consulta seja válida. Aceita até 100 pagamentos por requisição.

🔐 Permissão

• UserAuth — autenticação do usuário administrativo
• TRANSACTIONS_READ — escopo de permissão para leitura de transações financeiras e pagamentos

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

1{
2  "orderPaymentIds": [76, 77, 78]
3}

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/orders/payments/anti-fraud/consult' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "orderPaymentIds": [76, 77]
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "orderPaymentId": 76,
6      "antiFraudStatus": "approved",
7      "antiFraudScore": 12,
8      "error": null
9    },
10    {
11      "orderPaymentId": 77,
12      "antiFraudStatus": "review",
13      "antiFraudScore": 68,
14      "error": null
15    }
16  ]
17}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Erros por Pagamento (campo error)

🛡️ Envio para Antifraude

📋 Descrição

Endpoint responsável por enviar pagamentos de pedido para análise antifraude, disparando a verificação na integração antifraude configurada na loja.

Utilizado quando a análise antifraude não é disparada automaticamente no checkout ou quando é necessário reenviar um pagamento para reanálise.

Aceita até 100 pagamentos por requisição.

🔐 Permissão

• UserAuth — autenticação do usuário administrativo
• TRANSACTIONS_READ — escopo de permissão para leitura de transações financeiras e pagamentos
• ORDER_WRITE — escopo de permissão para operações de escrita em pedidos

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

1{
2  "payments": [
3    { "orderPaymentId": 76, "paymentAntiFraudCredentialId": null },
4    { "orderPaymentId": 77, "paymentAntiFraudCredentialId": 3 }
5  ]
6}

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/orders/payments/anti-fraud/send' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "payments": [
7      { "orderPaymentId": 76, "paymentAntiFraudCredentialId": null }
8    ]
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "orderPaymentId": 76,
6      "antiFraudStatus": "approved",
7      "error": null
8    },
9    {
10      "orderPaymentId": 77,
11      "antiFraudStatus": "review",
12      "error": null
13    }
14  ]
15}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Erros por Pagamento (campo error)