Skip to main content
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.

​
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

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.