Quickstart

This is the shortest partner flow that creates a customer, creates an operation, uploads documents, and reads the final analysis posture. All partner API calls use signed headers:

X-PayFi-Api-Key: pfk_test_...
X-PayFi-Nonce: random-128-bit-value
X-PayFi-Signature: t=1779100000000,h=<sha256_raw_body_hex>,v1=<hmac_hex>
Idempotency-Key: partner-write-key

1. Create or update a customer

POST /v1/customers

{
  "partnerCustomerId": "acme-customer-123",
  "legalName": "Acme Ltda",
  "taxId": "12.345.678/0001-95",
  "cnae": "4691-5/00",
  "email": "financeiro@acme.example"
}

{
  "customerId": "cus_example",
  "partnerCustomerId": "acme-customer-123",
  "legalName": "Acme Ltda"
}

2. Create the operation

POST /v1/operations

{
  "customerId": "cus_example",
  "operationType": "IMPORT_GOODS",
  "exchangeModality": "TERM",
  "partnerOperationId": "acme-op-123",
  "declaredBeneficiaryName": "Shenzhen NovaTech Components Co Ltd",
  "declaredEconomicOwnerName": "Shenzhen NovaTech Components Co Ltd",
  "buyerCountry": "BR"
}

declaredBeneficiaryName, declaredEconomicOwnerName, and buyerCountry are nullable for legacy compatibility, but the guided trust-v2 flow requires all three. PayFi does not infer the economic owner from the customer or importer name. The two-letter ISO buyer country controls country-specific validation such as CNPJ; an absent country never causes PayFi to assume Brazil.

{
  "operationId": "op_example",
  "partnerOperationId": "acme-op-123",
  "status": "REQUIREMENTS_PENDING",
  "requirementsStatus": "PENDING"
}

PayFi then prepares the required document list. Wait for operation.requirements.ready before collecting files for the operation.

3. Register each document

After the requirement list is approved, register each document before uploading bytes. POST /v1/operations/{operationId}/documents

{
  "documentType": "invoice",
  "fileName": "invoice-123.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 123456
}

{
  "documentId": "doc_example",
  "status": "UPLOAD_PENDING",
  "uploadUrl": "https://storage.example.com/presigned-upload",
  "uploadUrlExpiresInSeconds": 300
}

4. Upload and complete

Upload the file bytes directly to uploadUrl:

PUT https://storage.example.com/presigned-upload
Content-Type: application/pdf
Content-Length: 123456

Then complete the upload: POST /v1/upload-sessions/{token}/documents/{documentId}/complete

{
  "documentId": "doc_example",
  "status": "CLEAN",
  "operationStatus": "DOCUMENTS_UPLOADED"
}

5. Read status and analysis posture

Use GET /v1/operations/{operationId} for partner reconciliation:

{
  "operationId": "op_example",
  "partnerOperationId": "acme-op-123",
  "customerId": "cus_example",
  "status": "READY_FOR_MANUAL_REVIEW",
  "operationType": "IMPORT_GOODS",
  "exchangeModality": "TERM",
  "declaredBeneficiaryName": "Shenzhen NovaTech Components Co Ltd",
  "declaredEconomicOwnerName": "Shenzhen NovaTech Components Co Ltd",
  "buyerCountry": "BR",
  "requirementsStatus": "APPROVED",
  "requiredDocumentTypes": ["invoice", "bill_of_lading", "packing_list"],
  "missingDocumentTypes": [],
  "score0To100": 94,
  "score1To10": 10,
  "riskLevel": "low",
  "createdAt": "2026-05-20T12:00:00.000Z",
  "updatedAt": "2026-05-20T12:10:00.000Z"
}

Partners should also subscribe to signed webhooks for asynchronous updates. The API Reference includes endpoint-level examples for the ACTION_REQUIRED path where a required document type is still missing after analysis.

Integration

Trust and release

Authentication

1. Create or update a customer

2. Create the operation

3. Register each document

4. Upload and complete

5. Read status and analysis posture

​1. Create or update a customer

​2. Create the operation

​3. Register each document

​4. Upload and complete

​5. Read status and analysis posture

1. Create or update a customer

2. Create the operation

3. Register each document

4. Upload and complete

5. Read status and analysis posture