> ## 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.

# Operation Flow

> Create and track an FX operation.

The partner creates an operation after the customer is already registered. PayFi creates a durable operation ID from the minimal operation contract, runs an initial document-requirement assessment, and only releases upload after the document list is approved or auto-approved by the partner configuration.

PayFi is not the system of record for the FX trade. The partner platform remains the commercial and approval system. PayFi receives the operation context, collects supporting documents, produces a structured compliance analysis, and returns the result to the partner after human review.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Partner as Partner platform
    participant PayFi as PayFi API
    participant Client as Client / document owner
    participant Storage as Private object storage
    participant Analysis as Analysis worker
    participant Reviewer as Human reviewer

    Partner->>PayFi: POST /v1/operations
    PayFi-->>Partner: operationId, REQUIREMENTS_PENDING
    PayFi->>Analysis: Queue document requirement assessment
    Analysis-->>PayFi: Required documents with policy/RAG sources
    PayFi->>Reviewer: Review document requirements when configured
    Reviewer->>PayFi: Confirm required document list
    PayFi-->>Partner: operation.requirements.ready webhook
    Partner-->>Client: Share approved upload flow
    Client->>PayFi: Register approved document metadata
    PayFi-->>Client: Presigned uploadUrl
    Client->>Storage: PUT file bytes
    Client->>PayFi: Complete upload session
    PayFi->>Analysis: Queue document analysis job
    Analysis->>Analysis: OCR, extraction, validation, scoring
    Analysis-->>PayFi: Typed redacted result
    PayFi->>Reviewer: READY_FOR_MANUAL_REVIEW or ACTION_REQUIRED
    Reviewer->>PayFi: Record final review decision
    PayFi-->>Partner: Signed webhook with final manual decision
```

## Operational responsibilities

The partner owns:

* FX closing, customer relationship, and commercial approval.
* Creating the PayFi operation with `customerId`, `operationType`, `exchangeModality`, `declaredBeneficiaryName`, `declaredEconomicOwnerName`, and the ISO alpha-2 `buyerCountry`.
* Sharing the upload link only after PayFi emits `operation.requirements.ready`.
* Final business action after PayFi sends the signed callback.

PayFi owns:

* Policy/RAG-backed initial document requirement assessment.
* Required document tracking after requirement review or partner auto-approval.
* Secure document intake and object metadata verification.
* Analysis orchestration, including OCR, extraction, deterministic checks, AI-assisted classification, score calculation, and evidence preparation.
* Human review workflow and signed callback delivery.

The client owns:

* Uploading the documents requested for the operation.
* Re-uploading corrected or missing documents when PayFi returns `ACTION_REQUIRED` or the reviewer requests changes.

## Status model

```mermaid theme={null}
stateDiagram-v2
    [*] --> REQUIREMENTS_PENDING: POST /v1/operations
    REQUIREMENTS_PENDING --> REQUIREMENTS_REVIEW_REQUIRED: requirement workflow completed
    REQUIREMENTS_PENDING --> AWAITING_DOCUMENTS: auto-approved by partner config
    REQUIREMENTS_PENDING --> REQUIREMENTS_FAILED: requirement workflow failed
    REQUIREMENTS_REVIEW_REQUIRED --> AWAITING_DOCUMENTS: operator approves document list
    REQUIREMENTS_FAILED --> REQUIREMENTS_PENDING: retry
    AWAITING_DOCUMENTS --> DOCUMENTS_PARTIAL: one or more clean docs
    AWAITING_DOCUMENTS --> DOCUMENTS_UPLOADED: all required docs clean
    DOCUMENTS_PARTIAL --> DOCUMENTS_UPLOADED: remaining docs clean
    DOCUMENTS_UPLOADED --> PROCESSING: analysis job starts
    PROCESSING --> READY_FOR_MANUAL_REVIEW: analysis completed
    PROCESSING --> ACTION_REQUIRED: missing or inconsistent evidence
    PROCESSING --> PROCESSING_FAILED: retry budget exhausted
    ACTION_REQUIRED --> DOCUMENTS_PARTIAL: corrected docs requested
    ACTION_REQUIRED --> PROCESSING: analysis can continue
    READY_FOR_MANUAL_REVIEW --> MANUAL_REVIEW_APPROVED: human approval
    READY_FOR_MANUAL_REVIEW --> MANUAL_REVIEW_REJECTED: human rejection
    READY_FOR_MANUAL_REVIEW --> MANUAL_REVIEW_CHANGES_REQUESTED: human requests changes
    MANUAL_REVIEW_APPROVED --> PARTNER_CALLBACK_PENDING
    MANUAL_REVIEW_REJECTED --> PARTNER_CALLBACK_PENDING
    MANUAL_REVIEW_CHANGES_REQUESTED --> PARTNER_CALLBACK_PENDING
    PARTNER_CALLBACK_PENDING --> PARTNER_CALLBACK_DELIVERED
    PARTNER_CALLBACK_PENDING --> PARTNER_CALLBACK_FAILED
    PARTNER_CALLBACK_FAILED --> PARTNER_CALLBACK_PENDING: retry
```

The normal happy path is:

`REQUIREMENTS_PENDING` -> `REQUIREMENTS_REVIEW_REQUIRED` -> `AWAITING_DOCUMENTS` -> `DOCUMENTS_UPLOADED` -> `PROCESSING` -> `READY_FOR_MANUAL_REVIEW` -> `MANUAL_REVIEW_APPROVED` -> `PARTNER_CALLBACK_DELIVERED`.

The partial-document path is:

`AWAITING_DOCUMENTS` -> `DOCUMENTS_PARTIAL` -> `DOCUMENTS_UPLOADED`.

The remediation path is:

`PROCESSING` -> `ACTION_REQUIRED` -> `DOCUMENTS_PARTIAL` or `PROCESSING`, depending on whether new files are required.

## Analysis outcomes

The document analysis result is an operational decision aid, not a final approval. A successful technical analysis can still require partner action.

Correct documents with strong evidence move the operation to `READY_FOR_MANUAL_REVIEW`. The `GET /v1/operations/{operationId}` API Reference page includes the full response example for this path.

A wrong document type is not treated as an infrastructure failure. For example, if the partner declares `documentType: "invoice"` but uploads a packing list, the document can still be `PROCESSED` and the job can still be `SUCCEEDED`; the operation becomes `ACTION_REQUIRED` because the required invoice evidence is missing.

The `GET /v1/operations/{operationId}` API Reference page includes the full `ACTION_REQUIRED` example with `missingDocumentTypes: ["invoice"]`, low score, and critical risk.

## API sequence

1. Upsert the customer with `POST /v1/customers`.
2. Create the operation with `POST /v1/operations` using `customerId`, `operationType`, `exchangeModality`, `declaredBeneficiaryName`, `declaredEconomicOwnerName`, and `buyerCountry`. The fields remain nullable for legacy clients, but the guided trust-v2 flow requires them. Country-specific identifiers are validated only when their party country is explicitly known.
3. Wait for `operation.requirements.ready`.
4. Register and upload documents with the approved document types.
5. Confirm upload with `POST /v1/upload-sessions/{token}/documents/{documentId}/complete`.
6. Poll `GET /v1/operations/{operationId}` or consume signed webhooks.
7. Wait for the final signed webhook after human review.

For list views and partner reconciliation, use `GET /v1/operations` with `operationId`, `partnerOperationId`, `customerId`, `search`, `page`, and `limit`. To show the full history for one customer, use `GET /v1/customers/{customerId}/operations`; it returns the same paginated response shape and remains scoped to the signed partner integration.

## Review boundary

Analysis can classify, score, flag, and prepare evidence. It never approves an operation automatically.

Only a human review decision can move an operation to approved, rejected, or changes requested. This matches the operating model discussed for bank and FX partners: PayFi should reduce manual work and fraud risk, but the final approval remains human.

## Deployment note

The default integration model is PayFi-hosted API plus private object storage. For larger institutions with stricter LGPD, audit, or data-residency constraints, the same operational contract can be deployed in a private or on-premise environment while keeping the partner-facing API shape unchanged.