> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfi.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Import operation scoring

> Evidence, provisional scores and human review under the versioned PayFi import policy.

Contract v3 evaluates imports of goods under the standard, versioned PayFi policy. Each integration uses an explicitly activated configuration. Historical contract-v1 and contract-v2 results remain readable.

## What the score means

The score ranges from 0 to 100. A higher number means less risk identified in the facts checked by the PayFi policy. It is not a statistical probability of fraud or an automatic approval.

`score = max(0, 100 − sum of applicable impacts)`

| Finding severity | Impact |
| ---------------- | -----: |
| Informational    |      0 |
| Low              |     −5 |
| Medium           |    −20 |
| High             |    −40 |
| Critical         |    −70 |

Version 1 uses bands of 85–100 (low), 65–84 (medium), 40–64 (high), and 0–39 (critical). These are PayFi policy choices. The same issue is counted once per commercial obligation, entity and field; corroborating documents add evidence.

## Result states

| State         | Meaning                                                                                                          | Score                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `FINAL`       | Every required applicable check concluded, including checks that found violations.                               | Calculated value                     |
| `PROVISIONAL` | At least one usable commercial document proves the parties, amount and currency; required checks remain pending. | Calculated value from known findings |
| `UNAVAILABLE` | The minimum reliable documentary basis is missing or a technical failure prevents its use.                       | `null`                               |

Coverage is the share of required applicable checks that reached `PASS` or `FAIL`. `NOT_APPLICABLE` checks and excluded functionality are not in the denominator. Missing evidence is `NOT_VERIFIED`. A provisional score cannot be presented as an operation cleared for payment. Legacy scalar score fields are populated only for final v3 results.

## Commercial context and documents

Before shipment, a proforma or invoice can establish the commercial terms and bank instructions. One file can satisfy multiple requirements. After shipment, PayFi requires a commercial invoice and the transport document appropriate to the mode. Declared or documented nationalization requires DI/DUIMP; a packing list is required when needed to reconcile the cargo.

Record the phase, payment and shipment dates, and allocations to invoices. A partial payment must match the documented installment and remaining balance after evidenced previous payments. Multiple invoices require explicit allocations. Different currencies require an evidenced contractual conversion with rate, date, source and currencies. A third-party beneficiary requires an authorization or assignment linked to the seller and invoice.

Payment amounts use decimal arithmetic and a tolerance of two minor currency units. Differences above that tolerance are low up to 1%, medium above 1% up to 5%, high above 5% up to 10%, and critical above 10%. Currency or identity contradictions, unrelated transaction references, and commercial inconsistencies are evaluated with the supporting evidence.

Customer risk contributes 0, 20 or 40 points of impact for low, medium or high risk. Missing assessments or assessments older than 180 days keep the result provisional. PayFi exposure alerts use USD 50,000 per operation and USD 250,000 per month. A current customer-specific limit replaces the corresponding default. Exposure is checked again under a transaction lock before the human decision.

## Evidence and review

Every document fact includes its source document hash, page and excerpt. The extraction processes accepted pages in bounded chunks and reports incomplete reading. A scanned document, absent PDF metadata or missing document does not alone establish fraud. Sanctions, PEP and external screening are outside this version's scope.

The operator can inspect declared and documented values, open available source files, correct data or documents, and request reanalysis. Each material change invalidates the current result and creates another auditable revision. Raw files remain subject to the existing retention period; expired sources must be uploaded again.

Approving against findings or a provisional result requires confirmation and a reason tied to the current revision. A stale revision is rejected. The operator must load and confirm the new revision; their draft justification is retained. The human decision does not change the computed score. Unavailable scores cannot be approved through this flow.

## Activation and rollback

Consumers support v2 and v3 before activation. The release configuration records workflow versions and hashes, policy version and hash, extraction model, OCR and regulatory corpus provenance. Activated policy versions are immutable. Changes create another configuration.

The release command in the API repository, `npm run scoring:release -- manifest.json`, verifies the live workflow hashes and prints a dry run. Adding `--apply` publishes each integration's configuration atomically, invalidates open results and queues required extraction. A manifest can instead select a previous activation for rollback. Closed decisions and v3 history remain stored. A changed activation pointer causes the command to reject the stale manifest.

The runtime tracks technical failures, elapsed processing time, coverage, result states and finding impacts. Activation does not enable a disabled integration or change its external callback configuration.