Mandatory antifraud integration requirements

Set of prerequisites and minimum implementation and operations obligations. Exact scope (whether pre-analysis is used, timelines, commercial SLAs, support channels) must be mirrored in the contract or technical appendix; where the contract is silent, published product rules in the official reference apply.

Internal complementary documentation: readme-io-antifraud-overview.md · item types index.

1. Acceptance and scope of obligation

The contractor declares that:

It will implement antifraud flows according to the agreed model (with or without pre-analysis, evaluation after or before authorization — see §3).
It will maintain endpoints, logs, and processes required for callbacks, outbound notifications (PATCH), and reconciliation for the entire contract term.
It will not go to production with integrations that have not passed certification / UAT (sandbox) with success, pending, decline scenarios and, where applicable, strategies (§6).

2. General prerequisites (before any API call)

2.1 Infrastructure and security

ID	Requirement	Mandatory
INF1	Expose valid HTTPS (TLS) on all endpoints that receive antifraud notifications (`callback_url`).	Yes
INF2	Ability to handle calls with multi-second latency and controlled HTTP client timeouts; the API may return a partial synchronous response and complete in the background.	Yes
INF3	Secure storage of credentials (tokens, keys) outside public repositories; rotation per contracting party policy.	Yes
INF4	Idempotency when processing inbound notifications (same event or replay must not cause duplicate side effects: second capture, duplicate order release, etc.).	Yes
INF5	Origin validation for callback traffic (TLS, IP allowlists, or payload signing, when the contracting party documents the official method).	Yes when required by the contracting party

2.2 Data and compliance

ID	Requirement	Mandatory
DAT1	Collect and send `buyer`, `device`, `store`, `items`, `payments`, `transaction` per the OpenAPI contract for Create Evaluation / Create Pre-Evaluation.	Yes
DAT2	Ensure quality and accuracy of submitted data (documents, amounts, order identifiers); insufficient or inconsistent data undermines analysis and may breach obligations to the contracting party.	Yes
DAT3	Process personal data under Brazil’s LGPD (Lei Geral de Proteção de Dados) and the contracting party’s policies (lawful basis, retention, anonymization in operational logs where applicable).	Yes

2.3 Unique order identification

ID	Requirement	Mandatory
COR1	Define and maintain a stable `reference_id` per business transaction (`store.reference_id` / `transaction.reference_id`), unique in the merchant’s universe, reused between pre-evaluation and evaluation when both exist.	Yes
COR2	Persist the `evaluation_id` returned by the API to correlate callbacks, status `GET`, `DELETE`, and notification `PATCH` calls.	Yes

2.4 Certification / UAT

ID	Requirement	Mandatory
HOM1	Run sandbox tests using email patterns in Testing environment (e.g. `+autoaccept+`, `+autoreject+`, `+autoinprogress+`, 3DS flows when contracted).	Yes before go-live
HOM2	Record test evidence (requests/responses or transaction IDs) per the contracting party’s checklist.	Yes when requested
HOM3	During certification, execute and pass UAT on all use cases supplied by Koin (scripts, test data, API sequences, and expected outcomes sent by Koin as part of the certification program). Ad hoc tests by the contractor alone are not sufficient: the official Koin scenario pack must be completed and documented.	Yes for certification / go-live when Koin certification is a contractual requirement

The contractor must track updates to certification use cases when Koin publishes a new UAT pack version or ties certification maintenance to re-running scenarios.

3. Flow phases — pre-analysis and analysis

3.1 Phase overview

The documented default product is:

Pre-evaluation (pre-analysis) — optional in the general guide, mandatory if the contract with the contracting party requires a preliminary decision before acquirer authorization.
Payment authorization — at the acquirer / payment provider (out of scope of this document, but ordered relative to antifraud per the chosen model).
Evaluation (full analysis) — always mandatory for antifraud integration under the “pre + post authorization” model.

The contractor must implement exactly the contracted model among:

Model	Pre-analysis	Full evaluation	Restriction
A — Recommended default	Optional (`POST .../pre-evaluations`)	Mandatory after authorization (`POST .../evaluations`)	If pre-evaluation was used, same `reference_id` on evaluation
B — Evaluation only	Do not use	Mandatory after authorization	—
C — Evaluation before authorization	Must not use pre-evaluation	Evaluation before capture/final authorization per agreement	Do not combine with pre-evaluation

Reference: Antifraud Services Flow.

3.2 Pre-analysis (`POST /v1/antifraud/pre-evaluations`)

Obligations when pre-analysis is in contractual scope:

ID	Obligation
PRE1	Send a complete payload per Create Pre-Evaluation, including `device` and session context when required by the contracting party.
PRE2	Interpret synchronous response (`approved`, `denied`, `received`) and score per the contracting party’s commercial policy (e.g. do not authorize payment on `denied`).
PRE3	Record `evaluation_id` / related identifiers returned, if applicable to the pre-evaluation flow.
PRE4	If the response is `received` or analysis continues in the background, wait for completion via `callback_url` (§5) and/or agreed timeout policy.

3.3 Full evaluation (`POST /v1/antifraud/evaluations`)

Obligations:

ID	Obligation
EVA1	Call whenever the contract covers antifraud on the transaction, after the agreed point in the flow (generally after authorization if pre-evaluation existed).
EVA2	Reuse the `reference_id` from pre-evaluation when it exists.
EVA3	Send `payments` consistent with the authorized instrument (card, PIX, etc.), per the OpenAPI discriminator.
EVA4	Handle `approved` / `denied` / `received` as in pre-analysis; do not capture or ship goods if policy requires blocking on `denied`.

3.4 Synchronous responses (operational reference)

Status (doc example)	Score (example)	Expected contractor behavior
`approved`	~0	Proceed per contract.
`denied`	~100	Do not proceed with capture/delivery per policy; audit and notify per runbook.
`received`	in progress	Treat as pending; wait for callback and/or poll status (`GET`).

4. Fingerprint, device, and session

The device object at the root of Create Pre-Evaluation and Create Evaluation is mandatory (object required by the API contract). Antifraud quality depends on session and device signals consistent with the channel (web, app).

For browser checkout or web payment journeys, the contractor must integrate device fingerprinting via the official solution in Koin’s JavaScript Integration: the JavaScript snippet tracks user interaction with the site and collects device information; the generated value must be sent in the antifraud payload inside device, in the fields required by the current OpenAPI for Create Evaluation / Create Pre-Evaluation.

4.1 Minimum obligations

ID	Obligation
DEV1	Send `device` on every pre-evaluation and every evaluation, with at least session and IP identification when the channel allows (e.g. `ip_address` per published schema).
DEV2	Mandatory device fingerprint integration (web): embed the JavaScript documented in JavaScript Integration on pages where the payer starts or completes payment; ensure it runs before submitting pre-evaluation/evaluation; pass the token / identifier returned by the snippet into the request body under `device` as defined in OpenAPI. Do not replace with a non-approved library without written authorization from the contracting party / Koin.
DEV3	On web channels, collect User-Agent and other schema-supported fields (cookies, resolution, language, etc.) when technically possible, without violating privacy beyond user consent.
DEV4	Do not reuse one user’s fingerprint in another user’s session; do not send generic static values in production.

Native-only channels (app) without a web checkout page: the contractor must follow the device/session collection equivalent indicated by Koin in the certification pack or contract; if no specific guidance exists, keep device as complete as possible and align with the integration team before go-live.

4.2 Non-compliance consequences

Missing fingerprint via JavaScript Integration on web flows, or intentional degradation of device signals, may be treated as breach of technical specification, failure of certification / UAT, and go-live blocking.

5. Callback (`callback_url`) — notifications from antifraud to the contractor

5.1 Mandatory behavior

If the contract covers asynchronous analysis completion (received status, later updates, strategies), the contractor must:

ID	Obligation
CBK1	Provide an HTTPS `callback_url` on pre-evaluation and/or evaluation requests when asynchronous flow is active.
CBK2	Implement an endpoint that returns HTTP 2xx after safe persistence of the payload (internal processing may be async, but the response must indicate acceptance).
CBK3	Process notifications idempotently (safe replays).
CBK4	Maintain availability and observability (logs, failure alerts) compatible with the SLA agreed with the contracting party.

5.2 Expected content (high level)

The exact body follows the published API contract; it generally includes evaluation status updates and metadata the contractor needs to update the order, reconcile with evaluation_id / reference_id, and trigger internal flows (release, block, prompt user action).

6. Antifraud strategies

Strategies are additional fraud-prevention mechanisms (verification codes, liveness, manual review, authentication recovery, etc.), documented in the official Strategies reference. The contractor must treat the Strategies page and the current OpenAPI (Create Evaluation, payment responses with antifraud) as source of truth: Koin may extend the type list.

6.1 General contractor obligations

ID	Obligation
EST1	Handle responses and callbacks indicating an active strategy (including `strategies` array with `type` and `link`), displaying the experience to the payer per UX agreed with the contracting party.
EST2	Do not ignore pending strategies: transactions requiring user action must stay blocked until the step completes, an outcome callback arrives, or timeout/cancellation per contract policy.
EST3	Map states such as Recovering (§7.2) to active strategies, including sending `PATCH` Status notifications when the order lifecycle changes after recovery.
EST4	For each instantiated strategy, persist `evaluation_id` / `reference_id`, `strategies[].type`, completion indicator, and do not log full `link` values in non-confidential logs (URLs may contain tokens).

6.2 Strategy type catalog (`strategies[].type`)

For integrations that return strategies (objects with type, and where applicable link — HTTPS URL for the payer to complete the step), the reference bundle in this repo (payments.yaml, antifraud response with strategies) lists the values below. Confirm the current enum in Strategies and in the published OpenAPI.

Type	Description (product semantics and Koin documentation)	What the contractor must implement
VerificationCode	Additional validation via verification code sent or requested over a secure channel (SMS, email, app, etc.) to prove possession of the factor or contact before releasing the flow.	Show code capture UX; if the API returns a `link`, route the payer per Koin instructions; do not complete capture/goods release while the strategy is pending unless there is an explicit abort policy.
Liveness	Liveness proof (biometric or equivalent flow) to reduce identity fraud.	Open `link` in a secure context (HTTPS, ideally controlled webview or in-app browser); ensure camera/mic permissions when required; wait for callback / GET status before treating the transaction as approved.
ManualVerification	Manual review by the risk chain; decision is not immediate on the default synchronous path.	Keep the order in pending review; monitor `callback_url` and `GET /v1/antifraud/evaluations/{id}`; inform the payer per UX and legal basis; after outcome, reflect in `PATCH` Status notifications if the contract requires.
CollectAuthRecovery	Authentication recovery / additional proof collection or re-authentication (“recovery” flow before proceeding).	Redirect or embed the flow from `link`; handle return to the merchant (product return URLs, if any); keep capture/delivery blocked until completion or timeout policy.

link field: URL provided by the platform for the payer to complete the step; treat as sensitive data (TTL, no exposure in third-party analytics).

6.3 Input parameters and lifecycle

The Create Evaluation body may include strategies_data and other optional fields to feed strategies — validate against the OpenAPI version in use.
Strategies interact with 3DS and payment flows when the product combines them; test scenarios with email + auto_inprogress_3ds2_* + are in Testing environment.
Certification (HOM1, HOM3) must cover at least one case per contracted strategy type present in the Koin certification pack.

7. `PATCH` notifications — contractor sends updates to antifraud

Endpoint: PATCH /v1/antifraud/notifications/{id} — Send Notifications.

{id} resolution: may be the evaluation_id returned by the API or the merchant-context reference_id (store.reference_id), via query field: EVALUATION_ID (default) or REFERENCE_ID — same rule as cancellation and status lookup.

Nature: these notifications are distinct from callback_url. Here the contractor informs antifraud of facts after evaluation (order lifecycle, chargeback, information requests, etc.).

7.1 Main notification types (send when the event occurs)

The contractor must send the correct type whenever the service contract with the contracting party requires it. The list below follows the summary in readme-io-antifraud-overview; exact PATCH body fields must be validated against the Send Notifications OpenAPI.

Type	Purpose	When the contractor must send (typical requirement)
Chargeback	Dispute / scheme-forced reversal on cards.	Always when the contracting party or acquirer reports chargeback on an already evaluated transaction, within the agreed operational window.
RFI (Request for Information)	Additional information request from the risk chain.	When there is a formal documentation or clarification request tied to the transaction; the contractor must wrap content per schema.
Status	Operational order/payment state change relative to the evaluated transaction.	Whenever state changes to a value covered by the contract (see subtypes §7.2).
Info	Supplementary information that does not fit only `Status` or `RFI`.	When the contracting party defines sending risk metadata, audit notes, or events that must appear in the antifraud dossier.

7.2 Status notification — subtypes (detail)

Status carries a subtype qualifying the change. The contractor must map internal lifecycle (ERP, OMS, gateway) to the correct subtype. Subtypes cited in the overview documentation include:

Status subtype	Typical operational meaning	Send obligation
Authorized	Payment authorized / financial commitment recognized at the agreed point.	When the contract requires explicit mirroring in antifraud after authorization.
Collected	Funds captured / received (order invoiced or payment settled per business rules).	After capture or equivalent, if required by contract.
Not Collected	No capture or effective charge within the expected window or scenario.	When the flow fails to result in charge after authorization or hold, per agreement.
Cancelled	Order or authorization cancelled before completing the expected cycle.	Whenever cancellation is risk-relevant (e.g. post-analysis, pre-capture cancellation).
Finalized	Definitive order closure (delivered, completed, no operational pending items).	When the contract requires closing the case in antifraud.
Refunded	Full or partial refund to the payer.	Whenever a refund is tied to the evaluated transaction.
Recovering	Transaction in recovery (e.g. post-antifraud strategy, retry, manual handling).	When order state reflects recovery aligned with Strategies; must stay consistent with callbacks and active strategies (EST3).

Note: exact subtype names (JSON enum) must be copied from the current notifications endpoint OpenAPI; use the table above as business → type mapping guidance.

7.3 Timings, retries, and audit

ID	Obligation
NOT1	Implement retry with backoff for transient failures (`5xx`, timeout) when calling `PATCH .../notifications`, without semantic duplication (idempotency per `notification` or business key, per API).
NOT2	Keep logs of sent notifications (type, subtype, `evaluation_id`/`reference_id`, timestamp, HTTP status) for the period required by the contracting party.
NOT3	On prolonged antifraud API unavailability, follow the contracting party’s runbook (queue, alert, no loss of chargeback events).

8. Other endpoints required by contract

Endpoint	Typical use	Mandatory
`GET /v1/antifraud/evaluations/{id}`	Reconciliation and double-check after callback or in support tooling.	Yes — maintain query capability when support SLA requires it.
`DELETE /v1/antifraud/evaluations/{id}`	Order cancelled before analysis completes.	Yes when cancellation occurs in that window and the contract requires informing antifraud.

field parameter: EVALUATION_ID or REFERENCE_ID, used consistently everywhere.

9. Delivery checklist (minimum for technical sign-off)

The contractor should request final sign-off only when all contract-applicable items are evidenced:

10. Official references (always refresh to the current version)

Flow: Antifraud Services Flow
Pre-evaluation: Create Pre-Evaluation
Evaluation: Create Evaluation
Status: Retrieve Evaluation Status
Cancellation: Cancel Evaluation
PATCH notifications: Send Notifications
Strategies: Strategies
Device fingerprint (web): JavaScript Integration
Test environment: Testing environment

Document generated for integration specification purposes. Example values (scores, URLs) are illustrative; the OpenAPI contract and the legal instrument with the contracting party always prevail.