3DS (3-D Secure) in Koin antifraud integration

This article explains how to run fraud analysis with Koin APIs (prioritizing pre-evaluation), sending a tokenized card (secure_token) and strategies_data, and how to use Koin's own 3DS flow when the response requires strong authentication by forwarding returned additional_info to the acquirer pre-authorization request.

The goal is to avoid depending on a separate antifraud provider or a second external 3DS flow when the contracted Koin product already covers risk analysis + 3DS2 in the same ecosystem.

Official references: Create Pre-Evaluation · Create Evaluation · Strategies · Antifraud Services Flow · local overview in readme-io-antifraud-overview.md.

1. Integration objective (antifraud + 3DS in Koin)

1. Always prioritize pre-evaluation — Create Pre-Evaluation (POST /v1/antifraud/pre-evaluations): this is the recommended step to get a preliminary risk decision before committing the transaction with the acquirer.
2. Analyze the transaction (pre-evaluation and/or full evaluation, depending on contract) by sending buyer, device, items, values, and payment using secure_token (no clear PAN transit). The request body in section 6 can be used for both .../pre-evaluations and .../evaluations.
3. Interpret the response: if risk policy requires 3-D Secure, the API may return strategies (for example CollectAuthRecovery with provider: 3DS2) and, for interactive flows, a link for the cardholder challenge.
4. Complete 3DS via Koin flow and forward the returned additional_info to the acquirer pre-authorization request (see section 8), instead of orchestrating a second antifraud engine just to trigger 3DS.

Mandatory order for 3DS with acquirer guarantee: to use 3DS aligned with strong authentication and liability shift, the antifraud call that generates 3DS context (typically pre-evaluation) must happen before the acquirer pre-authorization request. Only after the Koin 3DS flow is completed (frictionless or challenge) should additional_info be sent to the acquirer.

3-D Secure strengthens card transactions by authenticating the cardholder with the issuer. In Koin's stack this appears under strategies, usually with provider 3DS2, returning cryptographic identifiers in synchronous responses or async updates through callback_url / status queries, according to your API contract version.

2. Detailed flow: pre-evaluation -> 3DS (link) -> additional_info -> acquirer

Recommended merchant/gateway sequence from first Koin call to acquirer pre-authorization.

Step by step

1. Tokenize the card (POST /v1/payment/tokenize) and get secure_token (see section 4).
2. Call pre-evaluation — POST /v1/antifraud/pre-evaluations with full payload (buyer, device, items, payments with secure_token, strategies_data, transaction, store, callback_url, etc.). Do not call acquirer pre-authorization yet.
3. Read the response. Typical cases:
   • Frictionless: response may already contain strategies with provider: 3DS2, mode: Frictionless, and populated additional_info -> go to step 6.
   • Challenge: response may include strategies[] with type: CollectAuthRecovery, provider: 3DS2, and a link (authentication URL). Status may stay in progress (received or equivalent) until challenge completion.
4. Show the 3DS flow to the user using returned link: browser redirect, secure WebView/iframe (according to UX and security policies), or embedded flow as documented in Strategies.
5. Wait for 3DS completion. After challenge, Koin consolidates the result. Merchant receives approval (or status update) with 3DS identifiers in strategies[].additional_info via:
   • callback_url notification (idempotent processing), and/or
   • GET /v1/antifraud/evaluations/{id} (or equivalent endpoint per OpenAPI) until payload contains usable additional_info (CAVV, ECI, directory_server_transaction_id, etc.).
6. Call acquirer pre-authorization and send additional_info (or your acquirer mapping: AAV/CAVV, ECI, XID, Directory Server Transaction ID, 3DS spec version, etc.) in the same request so the network recognizes the transaction as 3DS-authenticated (see section 8).
7. Full evaluation — when required by product, execute POST /v1/antifraud/evaluations after acquirer authorization, reusing the same reference_id.

What the user sees when link is returned (challenge)

link is not a merchant-designed screen. It is the 3DS flow URL hosted by Koin/provider chain. In practice, checkout should:

• Send the cardholder to that URL (or load it in iframe/WebView with proper cookie and postMessage handling, when applicable).
• Keep the order in "card authentication pending" until callback or status query confirms completion with additional_info or final decision.

Illustrative response snippet for pending challenge (fictional URL; production links are opaque and should not be exposed in public logs):

{
  "evaluation_id": "8c517284-6700-4234-b712-235e2c1aedc2",
  "status": "received",
  "score": 50,
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Challenge",
      "link": "https://risk.example.koin/3ds/challenge?token=REDACTED"
    }
  ]
}

After challenge completion, the consolidated callback/response typically follows section 8.2 format (for example status: approved and populated additional_info).

Diagram (overview)

sequenceDiagram
  participant Merchant as Merchant/backend
  participant Koin as Koin Antifraud API
  participant UI as Checkout/app
  participant User as Cardholder
  participant Acquirer as Acquirer

  Merchant->>Koin: POST /v1/antifraud/pre-evaluations
  alt Frictionless
    Koin-->>Merchant: strategies + additional_info
    Merchant->>Acquirer: Pre-authorization + additional_info
  else Challenge (link)
    Koin-->>Merchant: strategies with 3DS link
    Merchant->>UI: Open link / WebView
    UI->>User: 3DS challenge flow
    User->>Koin: Completes authentication
    Koin-->>Merchant: callback_url or GET with approved + additional_info
    Merchant->>Acquirer: Pre-authorization + additional_info
  end
  Note over Merchant,Koin: Full evaluation (evaluations) after authorization, same reference_id

3. Device fingerprint in sandbox

For sandbox certification, load device fingerprint script from:

https://portal-dev.koin.com.br/risk/fingerprint/statics/b-track-min.js

This endpoint is for development/homologation risk environment. In production, use the snippet and base URL defined in JavaScript Integration. The generated session value (for example session_id) must be sent in device object for both Create Pre-Evaluation and Create Evaluation, according to active OpenAPI contract.

4. Tokenization in Payments API

To avoid sending clear PAN in antifraud calls:

1. In browser/app, cardholder enters card data.
2. Backend calls Payments API to tokenize card.

Sandbox endpoint: POST https://api-sandbox.koin.com.br/v1/payment/tokenize

Body (summary): object with transaction.reference_id (unique attempt identifier in your system) and card with number, expiration_month, expiration_year, security_code, holder_name, aligned with TokenizeCard schema in local payments.yaml.

Response: object containing secure_token, used in payment creation and, when applicable by contract, inside antifraud payments block.

Reference: Tokenize Card (operation name may vary; path above matches local OpenAPI bundle).

5. Pre-evaluation and full evaluation: payments with secure_token and strategies_data

Both POST /v1/antifraud/pre-evaluations and POST /v1/antifraud/evaluations use the same context model: tokenized-card payments, buyer, device, items, transaction, store, strategies_data, etc., as defined in Create Pre-Evaluation and Create Evaluation.

Prioritize sending the complete package in pre-evaluation so 3DS decision happens before acquirer pre-authorization.

For tokenized cards, in payments use the payment discriminator agreed by contract (typically credit card) and send the tokenization secure_token instead of clear card number.

Optional strategies_data carries merchant/acquirer context for 3DS/network-dependent strategies:

"strategies_data": {
  "acquirer": "WDP",
  "acquirer_bin": "448768",
  "collect_auth_supported": true,
  "mcc": "1234",
  "merchant_descriptor": "DAGS_TEST_3DS",
  "merchant_id": "BRLIARLEGAPR"
}

Validate which strategies_data keys are accepted/required in your exact API version OpenAPI.

6. Request example — fraud analysis with secure_token

Recommended sequence: first send this body to POST https://api-sandbox.koin.com.br/v1/antifraud/pre-evaluations; when full analysis after authorization is required, reuse the same reference_id on POST .../v1/antifraud/evaluations, per Antifraud Services Flow.

Sandbox endpoint - full evaluation (example): POST https://api-sandbox.koin.com.br/v1/antifraud/evaluations
Sandbox endpoint - pre-evaluation (recommended before acquirer): POST https://api-sandbox.koin.com.br/v1/antifraud/pre-evaluations

Headers: Content-Type: application/json, Accept: application/json, Authorization: Bearer <token>.

The JSON below is illustrative: standard fraud context (buyer, device, store, items, transaction) plus payments with discriminator type: CreditCard, the secure_token from tokenization, and strategies_data for 3DS strategies.

Adjust optional/required fields (address, phone, extra device fields) according to your OpenAPI and Try It panel.

{
  "type": "Ecommerce",
  "callback_url": "https://www.sua-loja.com.br/webhooks/antifraud-evaluation",
  "buyer": {
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "[email protected]",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    },
    "address": {
      "street": "Rua Exemplo",
      "number": "1000",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country_code": "BR",
      "zip_code": "01310100"
    }
  },
  "device": {
    "session_id": "5b8c20c3-45de-41bf-b243-87ad5d21bc3b",
    "ip_address": "192.0.2.146"
  },
  "store": {
    "code": "SBXSTORE",
    "reference_id": "PEDIDO-3DS-2026-00042",
    "category": "1234"
  },
  "items": [
    {
      "type": "Generic",
      "category": { "id": "CAT-001", "name": "Electronics" },
      "id": "SKU-998877",
      "name": "Wireless headphones",
      "price": { "currency_code": "BRL", "value": 299.9 },
      "quantity": 1
    }
  ],
  "payments": [
    {
      "type": "CreditCard",
      "amount": { "currency_code": "BRL", "value": 299.9 },
      "secure_token": "86198ce2640145ef2488e884b8ecb459d414700dc540f76ee6034824f6187e9ac3d100f3649650754d3a2592c0391c3f90d924d745fb7e6d0a9fae4cfa79c4e55f9ab1e00102c0a5c7a7e7c59cfff219c86c30c77b9e5509e224f293052f58c275123a",
      "installments": 1
    }
  ],
  "transaction": {
    "reference_id": "PEDIDO-3DS-2026-00042"
  },
  "strategies_data": {
    "acquirer": "WDP",
    "acquirer_bin": "448768",
    "collect_auth_supported": true,
    "mcc": "1234",
    "merchant_descriptor": "DAGS_TEST_3DS",
    "merchant_id": "BRLIARLEGAPR"
  }
}

Correlation rule: use the same store.reference_id and transaction.reference_id when business rules require a single order identifier (including pre-analysis flow). The secure_token above is a placeholder; replace with real token from tokenization response.

7. Test cards (sandbox) — 3DS scenarios

Use the cards below only in test environments. Labels are kept in Spanish as provided.

(1) Aprobacion con 3DS con desafio

"card": {
  "number": "4000000000002503",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(2) Aprobacion sin desafio (Frictionless)

"card": {
  "number": "4000000000001000",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(3) Frictionless con fallo

"card": {
  "number": "5200000000001013",
  "brand_code": "CA",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(4) 3DS con desafio con fallo

"card": {
  "number": "4000000000002644",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

Note: if your TokenizeCard schema does not include brand_code under card, send only required fields from your contract version.

Besides card numbers, antifraud docs also provide buyer email patterns to force scenarios (including 3DS2 paths before accept/reject): Testing environment and readme-io-antifraud-overview.md.

8. Response examples with identifiers (additional_info)

additional_info fields are the authentication proof that the acquirer must receive in pre-authorization (or equivalent host fields) to validate 3DS authentication and align guarantee/liability shift in card networks.

Forward additional_info as-is (or mapped per acquirer manual: CAVV, ECI, XID, directory_server_transaction_id, spec version, etc.) in the same pre-authorization transaction, after antifraud + Koin 3DS completion.

8.1 3DS2 success - Frictionless

When analysis is approved and 3DS2 runs in Frictionless mode, response can include:

{
  "id": "61317679-016",
  "analysis_type": "AUTOMATIC",
  "evaluation_id": "8c517284-6700-4234-b712-235e2c1aedc2",
  "score": 0,
  "status": "approved",
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Frictionless",
      "additional_info": {
        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "directory_server_transaction_id": "279d8fbf-f4cb-40a4-98ce-cb98193cdd86",
        "specification_version": "2.2.0",
        "eci": "05",
        "merchant_id": "BRLIARLEGAPR"
      }
    }
  ],
  "case_state": "CLOSED"
}

8.2 3DS2 success - Challenge (after cardholder completes challenge)

In pending phase, response usually carries mode: Challenge and a link (see section 2). After challenge completion in Koin flow, same evaluation_id may be updated via callback_url or GET with status: approved and populated additional_info.

{
  "id": "61420001-022",
  "analysis_type": "AUTOMATIC",
  "evaluation_id": "a4419c10-2b8e-4f1d-9c6a-1d0e3f7b2a88",
  "score": 0,
  "status": "approved",
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Challenge",
      "additional_info": {
        "cavv": "BwABBJQ1AgAAAElwAAAoAAAAAAA=",
        "xid": "BwABBJQ1AgAAAElwAAAoAAAAAAA=",
        "directory_server_transaction_id": "f3a4f1b2-9c0d-4e5f-a6b7-8c9d0e1f2a3b",
        "specification_version": "2.2.0",
        "eci": "05",
        "merchant_id": "BRLIARLEGAPR"
      }
    }
  ],
  "case_state": "CLOSED"
}

ECI and CAVV: real values vary by card brand, auth result, and network rules. Always use exactly what Koin returns for that evaluation_id.

Practical reading (Frictionless and Challenge):

Operational reminder: if these fields are not sent in acquirer pre-authorization, network may classify transaction as not 3DS-authenticated, impacting payment guarantee and chargeback liability.

Field-name mapping (CAVV/AAV, ECI, DS ID) is an acquirer/gateway technical contract. Koin integration responsibility is to provide faithful additional_info content after 3DS completion.

9. Flow summary

1. Load b-track-min.js (sandbox URL in section 3) and populate device in pre-evaluation and full evaluation.
2. POST /v1/payment/tokenize -> get secure_token.
3. POST /v1/antifraud/pre-evaluations (priority) with payments, strategies_data, and other required fields, before any acquirer pre-authorization.
4. If response indicates 3DS, follow Koin flow (link/challenge when applicable) until usable additional_info is available.
5. Send acquirer pre-authorization including additional_info (or mapped equivalent) for network-level 3DS guarantee.
6. Complete cycle with POST /v1/antifraud/evaluations when product requires post-authorization full analysis, reusing the same reference_id.

For formal integration requirements (pre-analysis, mandatory fingerprint, strategies, homologation), see antifraud-integration-requirements-contractor.md.

3DS (3-D Secure) na integração de antifraude Koin

Este artigo descreve como executar a análise de fraude com a API da Koin (priorizando pré-avaliação), enviando cartão tokenizado (secure_token) e strategies_data, e como aproveitar o 3DS da própria Koin quando a resposta indicar autenticação forte — encaminhando o additional_info devolvido para a pré-autorização na adquirente — sem depender de outro provedor só para antifraude nem de um segundo fluxo paralelo de 3DS de terceiros, quando o produto contratado cobre risco + 3DS2 no mesmo ecossistema.

Documentação oficial complementar: Create Pre-Evaluation · Create Evaluation · Strategies · Antifraud Services Flow · fluxo geral em readme-io-antifraud-overview.md.

1. Objetivo da integração (antifraude + 3DS na Koin)

1. Priorizar sempre a pré-avaliação — Create Pre-Evaluation (POST /v1/antifraud/pre-evaluations): é o passo recomendado para obter a decisão preliminar de risco antes de comprometer a transação na adquirente. Quando o produto permitir, use pré-avaliação por padrão e mantenha o reference_id estável para correlacionar com a avaliação completa depois, conforme o fluxo oficial.
2. Analisar a transação (pré-avaliação e/ou avaliação completa, conforme o contrato) enviando comprador, dispositivo, itens, valores e o pagamento com secure_token (dados de cartão não trafegam em claro). O exemplo de corpo na §6 aplica-se ao mesmo modelo de payload que você enviará na pré-avaliação ou na avaliação — ajuste o endpoint ao passo do fluxo (.../pre-evaluations vs .../evaluations).
3. Interpretar a resposta: se a política de risco exigir 3-D Secure, a API pode devolver estratégias (por exemplo CollectAuthRecovery com provider: 3DS2) e, em fluxos com interação, um link para o portador concluir o desafío — conforme Strategies e o guia de fluxo.
4. Concluir o 3DS pelo fluxo Koin e encaminhar o additional_info devolvido na estratégia 3DS2 para a pré-autorização na adquirente (ver §8) — em vez de orquestrar outro motor de antifraude só para disparar 3DS.

Ordem obrigatória para 3DS com garantia na adquirente: para utilizar o 3DS de forma alinhada à autenticação forte e ao liability shift, a chamada de antifraude que produz o contexto 3DS (em geral a pré-avaliação, e demais chamadas exigidas pelo produto) deve ocorrer antes da requisição de pré-autorização enviada à adquirente. Só depois de concluído o fluxo 3DS indicado pela Koin (frictionless ou desafío) é que os dados de additional_info devem seguir para a adquirente na pré-autorização — veja o reforço na §8.

O 3-D Secure em si fortalece transações com cartão (autenticação do portador perante o emissor). Na stack Koin isso aparece ligado ao provedor 3DS2 nas strategies, com retorno de dados criptográficos e identificadores na resposta síncrona ou em atualizações via callback_url / consulta de status, conforme o contrato da sua versão de API.

2. Fluxo detalhado: pré-avaliação → 3DS (link) → additional_info → adquirente

Sequência recomendada do ponto de vista do lojista / gateway, do primeiro contato com a Koin até a pré-autorização na adquirente.

Passo a passo

1. Tokenizar o cartão (POST /v1/payment/tokenize) e obter o secure_token (ver §4).
2. Chamar a pré-avaliação — POST /v1/antifraud/pre-evaluations com o payload completo (buyer, device, items, payments com secure_token, strategies_data, transaction, store, callback_url, etc.), conforme Create Pre-Evaluation. Não chame ainda a pré-autorização na adquirente.
3. Ler a resposta. Casos típicos:
   • Frictionless: a resposta já pode trazer strategies com provider: 3DS2, mode: Frictionless e additional_info preenchido — avance direto ao passo 6.
   • Com desafío: a resposta pode incluir strategies[] com type: CollectAuthRecovery, provider: 3DS2 e um link (URL do fluxo de autenticação). O status pode permanecer em análise (received / equivalente) até o portador concluir o 3DS — confira o contrato da sua versão.
4. Exibir o fluxo 3DS ao usuário usando o link retornado: redirecionar o navegador, abrir WebView / iframe seguro (conforme UX e políticas de segurança) ou embutir o fluxo indicado na documentação de Strategies. O portador completa o desafío (OTP, app do banco, etc.) no domínio do fluxo Koin / 3DS, não na adquirente.
5. Aguardar a conclusão do 3DS. Após o desafío, a Koin consolida o resultado. O lojista recebe a aprovação (ou atualização de status) com os identificadores 3DS em strategies[].additional_info via:
   • notificação callback_url (processar de forma idempotente), e/ou
   • GET /v1/antifraud/evaluations/{id} (ou endpoint equivalente para pré-avaliação, conforme OpenAPI), até que o payload contenha additional_info utilizável (CAVV, ECI, directory_server_transaction_id, etc.).
6. Chamar a adquirente — pré-autorização de pagamento enviando o additional_info (ou o mapeamento exigido pelo manual do gateway: AAV/CAVV, ECI, XID, ID do directory server, versão 2.2.0, etc.) junto ao pedido de pré-autorização, para que a rede reconheça a transação como autenticada em 3DS (ver §8).
7. Avaliação completa — quando o produto exigir, executar POST /v1/antifraud/evaluations após a autorização na adquirente, com o mesmo reference_id, conforme o fluxo oficial.

O que o usuário “vê” quando há link (desafío)

O campo link não é uma tela desenhada pelo lojista: é a URL do fluxo 3DS hospedado pela cadeia Koin/provedor. Na prática, o checkout do lojista deve:

• Encaminhar o portador para essa URL (ou carregá-la em iframe/WebView com políticas adequadas de cookies e postMessage, se aplicável);
• Manter o pedido em estado “aguardando autenticação do cartão” até receber o callback ou até o GET mostrar conclusão com additional_info ou decisão final.

Exemplo ilustrativo de trecho de resposta com desafío pendente (URL fictícia; em produção o link é opaco — não vazar em logs públicos):

{
  "evaluation_id": "8c517284-6700-4234-b712-235e2c1aedc2",
  "status": "received",
  "score": 50,
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Challenge",
      "link": "https://risk.example.koin/3ds/challenge?token=REDACTED"
    }
  ]
}

Após o portador concluir o desafío, uma resposta ou callback consolidado pode alinhar-se ao formato da §8.2 (por exemplo status: approved e additional_info com CAVV, ECI, etc.).

Diagrama (visão geral)

sequenceDiagram
  participant Loja as Lojista / backend
  participant Koin as API Antifraude Koin
  participant UI as Checkout / app
  participant User as Portador
  participant ADQ as Adquirente

  Loja->>Koin: POST /v1/antifraud/pre-evaluations
  alt Frictionless
    Koin-->>Loja: strategies + additional_info
    Loja->>ADQ: Pré-autorização + additional_info
  else Challenge (link)
    Koin-->>Loja: strategies com link 3DS
    Loja->>UI: Abrir link / WebView
    UI->>User: Fluxo 3DS (desafío)
    User->>Koin: Conclui autenticação
    Koin-->>Loja: callback_url ou GET com approved + additional_info
    Loja->>ADQ: Pré-autorização + additional_info
  end
  Note over Loja,Koin: Avaliação completa (evaluations) após autorização, mesmo reference_id

3. Device fingerprint em sandbox

Para homologação em sandbox, o script de device fingerprint deve ser carregado a partir da URL:

https://portal-dev.koin.com.br/risk/fingerprint/statics/b-track-min.js

Esse endpoint corresponde ao ambiente de desenvolvimento/homologação da solução de risco; em produção, use o snippet e a base URL indicados no guia oficial JavaScript Integration. O valor gerado pela sessão (por exemplo session_id) deve ser enviado no objeto device nos payloads de Create Pre-Evaluation e Create Evaluation, conforme o OpenAPI vigente.

4. Tokenização na API de Payments

Para não trafegar o PAN completo na avaliação de antifraude, o fluxo recomendado é:

1. No browser ou app, o portador informa os dados do cartão.
2. O backend chama a API de Payments para tokenizar o cartão.

Endpoint (sandbox): POST https://api-sandbox.koin.com.br/v1/payment/tokenize

Corpo (resumo): objeto com transaction.reference_id (identificador único da tentativa no seu sistema) e card com number, expiration_month, expiration_year, security_code, holder_name — alinhado ao schema TokenizeCard no bundle OpenAPI do repositório (payments.yaml).

Resposta: objeto com secure_token, que representa o cartão tokenizado para uso em criação de pagamento ou, quando aplicável ao contrato de antifraude, no bloco payments da avaliação.

Referência de produto: tokenização descrita em Tokenize Card (nome da operação pode variar ligeiramente na documentação pública; o path acima é o do payments.yaml local).

5. Pré-avaliação e avaliação completa: payments com secure_token e strategies_data

Na pré-avaliação (POST /v1/antifraud/pre-evaluations) e na avaliação completa (POST /v1/antifraud/evaluations), o corpo segue o mesmo tipo de informação de contexto: payments com cartão tokenizado, buyer, device, items, transaction, store, strategies_data, etc., conforme Create Pre-Evaluation e Create Evaluation. Priorize enviar o pacote completo já na pré-avaliação para que o 3DS seja decidido antes da pré-autorização na adquirente.

Para cartão tokenizado, em payments use o discriminador acordado com o contrato (tipicamente algo equivalente a cartão de crédito) e informe o secure_token retornado pela tokenização — sem reenviar o número do cartão em claro.

O objeto opcional strategies_data fornece contexto adquirência / lojista para estratégias que dependem de 3DS ou de parâmetros de rede. Exemplo ilustrativo (valores de teste):

"strategies_data": {
  "acquirer": "WDP",
  "acquirer_bin": "448768",
  "collect_auth_supported": true,
  "mcc": "1234",
  "merchant_descriptor": "DAGS_TEST_3DS",
  "merchant_id": "BRLIARLEGAPR"
}

Confirme no OpenAPI da versão que você integra quais chaves de strategies_data são aceitas e obrigatórias para o seu produto.

6. Exemplo de requisição — análise de fraude com secure_token

Fluxo recomendado: envie primeiro este corpo a POST https://api-sandbox.koin.com.br/v1/antifraud/pre-evaluations; em seguida, quando o produto exigir a análise completa após a autorização, repita o mesmo reference_id em POST .../v1/antifraud/evaluations, conforme Antifraud Services Flow.

Endpoint (sandbox) — avaliação completa (exemplo): POST https://api-sandbox.koin.com.br/v1/antifraud/evaluations
Endpoint (sandbox) — pré-avaliação (recomendado antes da adquirente): POST https://api-sandbox.koin.com.br/v1/antifraud/pre-evaluations

Cabeçalhos: Content-Type: application/json, Accept: application/json, Authorization: Bearer <token>.

O JSON abaixo é ilustrativo: junta o mínimo típico de contexto de fraude (buyer, device, store, items, transaction) com payments no discriminador type: CreditCard e o secure_token obtido em POST /v1/payment/tokenize, além de strategies_data para alimentar estratégias 3DS. Ajuste campos obrigatórios opcionais (endereço, telefone, campos extras de device) ao OpenAPI e ao Try it da documentação oficial.

{
  "type": "Ecommerce",
  "callback_url": "https://www.sua-loja.com.br/webhooks/antifraud-evaluation",
  "buyer": {
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "[email protected]",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    },
    "address": {
      "street": "Rua Exemplo",
      "number": "1000",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country_code": "BR",
      "zip_code": "01310100"
    }
  },
  "device": {
    "session_id": "5b8c20c3-45de-41bf-b243-87ad5d21bc3b",
    "ip_address": "192.0.2.146"
  },
  "store": {
    "code": "SBXSTORE",
    "reference_id": "PEDIDO-3DS-2026-00042",
    "category": "1234"
  },
  "items": [
    {
      "type": "Generic",
      "category": { "id": "CAT-001", "name": "Electronics" },
      "id": "SKU-998877",
      "name": "Wireless headphones",
      "price": { "currency_code": "BRL", "value": 299.9 },
      "quantity": 1
    }
  ],
  "payments": [
    {
      "type": "CreditCard",
      "amount": { "currency_code": "BRL", "value": 299.9 },
      "secure_token": "86198ce2640145ef2488e884b8ecb459d414700dc540f76ee6034824f6187e9ac3d100f3649650754d3a2592c0391c3f90d924d745fb7e6d0a9fae4cfa79c4e55f9ab1e00102c0a5c7a7e7c59cfff219c86c30c77b9e5509e224f293052f58c275123a",
      "installments": 1
    }
  ],
  "transaction": {
    "reference_id": "PEDIDO-3DS-2026-00042"
  },
  "strategies_data": {
    "acquirer": "WDP",
    "acquirer_bin": "448768",
    "collect_auth_supported": true,
    "mcc": "1234",
    "merchant_descriptor": "DAGS_TEST_3DS",
    "merchant_id": "BRLIARLEGAPR"
  }
}

Pontos de correlação: use o mesmo store.reference_id e transaction.reference_id quando sua regra de negócio exigir um único identificador de pedido (incluindo fluxo com pré-análise — ver readme-io-antifraud-overview.md). O secure_token do exemplo é placeholder; troque pelo token real retornado na tokenização.

7. Cartões de teste (sandbox) — cenários 3DS

Use os cartões abaixo apenas em ambiente de testes. Os rótulos descrevem o comportamento esperado para homologação (nomenclatura em espanhol conforme solicitado).

(1) Aprobación con 3DS con desafío

"card": {
  "number": "4000000000002503",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(2) Aprobación sin desafío (Frictionless)

"card": {
  "number": "4000000000001000",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(3) Frictionless con fallo

"card": {
  "number": "5200000000001013",
  "brand_code": "CA",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

(4) 3DS con desafío con fallo

"card": {
  "number": "4000000000002644",
  "brand_code": "VI",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "876",
  "holder_name": "Juan Perez"
}

Nota: se o schema TokenizeCard da sua versão não listar brand_code no mesmo nível de card, envie apenas os campos exigidos pelo contrato e use o cartão de teste que o time Koin indicar para o BIN/marca desejados.

Além dos cartões, a documentação de antifraude descreve padrões em e-mail do comprador para forçar cenários (incluindo variantes 3DS2 antes de aceitar ou rejeitar): ver Testing environment e a tabela em readme-io-antifraud-overview.md.

8. Exemplos de resposta com identificadores (additional_info)

Os campos em additional_info são os identificadores e provas que a adquirente precisa receber na pré-autorização (ou no campo equivalente do host de pagamento) para comprovar a autenticação 3DS e alinhar garantia / liability shift à rede — repasse o additional_info integralmente (ou o mapeamento exigido pelo manual da adquirente: CAVV, ECI, XID, directory_server_transaction_id, versão da especificação, etc.) na mesma transação em que solicita a pré-autorização, após o antifraude e o 3DS Koin terem sido executados antes dessa chamada.

8.1 Sucesso 3DS2 — Frictionless

Quando a análise conclui com aprovação e o 3DS2 corre em modo Frictionless, a resposta síncrona (ou um estado consolidado consultável) pode incluir strategies semelhante ao exemplo abaixo (sem passo interativo de link).

{
  "id": "61317679-016",
  "analysis_type": "AUTOMATIC",
  "evaluation_id": "8c517284-6700-4234-b712-235e2c1aedc2",
  "score": 0,
  "status": "approved",
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Frictionless",
      "additional_info": {
        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "directory_server_transaction_id": "279d8fbf-f4cb-40a4-98ce-cb98193cdd86",
        "specification_version": "2.2.0",
        "eci": "05",
        "merchant_id": "BRLIARLEGAPR"
      }
    }
  ],
  "case_state": "CLOSED"
}

8.2 Sucesso 3DS2 — Challenge (após o portador concluir o desafío)

Na fase pendente, a resposta costuma trazer mode: Challenge e um link (ver §2). Depois que o portador finaliza o desafío no fluxo Koin, o mesmo evaluation_id pode ser atualizado via callback_url ou GET com status: approved e additional_info preenchido — sem link na estratégia consolidada (ilustrativo; nomes exatos dependem do OpenAPI).

{
  "id": "61420001-022",
  "analysis_type": "AUTOMATIC",
  "evaluation_id": "a4419c10-2b8e-4f1d-9c6a-1d0e3f7b2a88",
  "score": 0,
  "status": "approved",
  "strategies": [
    {
      "type": "CollectAuthRecovery",
      "provider": "3DS2",
      "mode": "Challenge",
      "additional_info": {
        "cavv": "BwABBJQ1AgAAAElwAAAoAAAAAAA=",
        "xid": "BwABBJQ1AgAAAElwAAAoAAAAAAA=",
        "directory_server_transaction_id": "f3a4f1b2-9c0d-4e5f-a6b7-8c9d0e1f2a3b",
        "specification_version": "2.2.0",
        "eci": "05",
        "merchant_id": "BRLIARLEGAPR"
      }
    }
  ],
  "case_state": "CLOSED"
}

ECI e CAVV: os valores reais variam por marca de cartão, resultado da autenticação e regra da rede. Use sempre o conjunto devolvido pela Koin naquele evaluation_id, sem substituir por constantes de exemplo.

Leitura prática (Frictionless e Challenge):

Reforço operacional: sem encaminhar esses dados na pré-autorização com a adquirente, a rede pode tratar a transação como não autenticada no padrão 3DS, com impacto em garantia de pagamento e responsabilidade por chargeback. O mapeamento exato dos nomes de campos (CAVV/AAV, ECI, DS ID) para o gateway da adquirente é contrato técnico entre lojista e adquirente; o papel da integração Koin é fornecer o conteúdo de additional_info fielmente após o fluxo 3DS.

Em cenários com desafío, a documentação de Strategies e o guia de fluxo antifraude orientam o uso de link ou fluxos embutidos para o portador concluir a etapa; somente após o 3DS concluído e o additional_info disponível é que a pré-autorização na adquirente deve ser enviada com esses campos. A decisão de risco pode ainda chegar por callback_url ou atualização de status — trate notificações de forma idempotente.

9. Resumo do fluxo

1. Carregar b-track-min.js (sandbox: URL deste artigo §3) e popular device na pré-avaliação e na avaliação completa.
2. POST /v1/payment/tokenize → obter secure_token.
3. POST /v1/antifraud/pre-evaluations (prioritário) com payments, strategies_data e demais campos — antes de qualquer pré-autorização na adquirente (corpo como na §6, trocando só a URL).
4. Se a resposta indicar 3DS, seguir o fluxo Koin (link / desafío se houver) até existir additional_info utilizável — detalhe passo a passo na §2.
5. Enviar a pré-autorização à adquirente incluindo o additional_info (ou mapeamento equivalente) para garantia 3DS na rede.
6. Concluir o ciclo com POST /v1/antifraud/evaluations quando o produto exigir análise completa após a autorização, reutilizando o mesmo reference_id, conforme readme-io-antifraud-overview.md.

Para requisitos formais de integração (pré-análise, fingerprint obrigatório, estratégias, homologação), ver também requisitos-integracao-antifraude-contratada.md.