Trade Finance Rail

The Trade Finance Rail provides APIs for managing Letters of Credit (LC), bank guarantees, documentary collections, and trade presentations, aligned with UCP 600 international standards.

Overview

The Trade Finance Rail supports the complete documentary trade cycle:

Capability	Description
LC Issuance	Issue, amend, and manage Letters of Credit (UCP 600)
Document Presentations	Receive, review, and process trade presentations
Discrepancy Management	Identify, communicate, and resolve document discrepancies
Settlement	Initiate and complete trade settlement

Standards Compliance

The Trade Finance Rail is aligned with:

Standard	Description
UCP 600	ICC Uniform Customs and Practice for Documentary Credits (2007 rev.)
ISBP 821	International Standard Banking Practice
eUCP 2.0	Electronic supplement to UCP for digital presentations
SWIFT MT7xx	SWIFT trade finance message standards
ISO 20022	Financial messaging standard for trade finance

Endpoints

List Trade Presentations

GET /api/v1/trade/presentations

Lists all documentary presentations for the authenticated tenant.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status (received, under_review, accepted, rejected, discrepant)
`lcId`	string	Filter by Letter of Credit ID
`fromDate`	string	Filter from presentation date (ISO 8601)
`toDate`	string	Filter to presentation date (ISO 8601)
`page`	number	Page number (default: 1)
`perPage`	number	Items per page (default: 20, max: 100)

Create Trade Presentation

POST /api/v1/trade/presentations

Registers a new documentary presentation under an LC.

Request Body:

{
  "lcId": "lc_abc123",
  "presentingBankBic": "RIBLSARIXXX",
  "presentationDate": "2024-01-15",
  "documents": [
    {
      "type": "commercial_invoice",
      "documentNumber": "INV-2024-001",
      "documentDate": "2024-01-12",
      "amount": { "amount": 450000, "currency": "USD" },
      "fileReference": "file_doc_001"
    },
    {
      "type": "bill_of_lading",
      "documentNumber": "BL-2024-001",
      "documentDate": "2024-01-13",
      "portOfLoading": "AEJEA",
      "portOfDischarge": "SAJED",
      "fileReference": "file_doc_002"
    },
    {
      "type": "certificate_of_origin",
      "documentNumber": "COO-2024-001",
      "issuingAuthority": "Dubai Chamber of Commerce",
      "fileReference": "file_doc_003"
    }
  ],
  "draftAmount": { "amount": 450000, "currency": "USD" },
  "usanceTermDays": 90
}

Response:

{
  "data": {
    "id": "pres_xyz789",
    "status": "received",
    "lcId": "lc_abc123",
    "presentationDate": "2024-01-15",
    "expiryDate": "2024-01-19",
    "documents": [
      {
        "type": "commercial_invoice",
        "documentNumber": "INV-2024-001",
        "status": "pending_review"
      }
    ],
    "draftAmount": { "amount": 450000, "currency": "USD" },
    "discrepancyCount": 0,
    "createdAt": "2024-01-15T08:00:00Z",
    "updatedAt": "2024-01-15T08:00:00Z"
  }
}

Review Presentation

POST /api/v1/trade/presentations/{id}/review

Initiates the documentary examination process under UCP 600 Article 14.

Request Body:

{
  "examinerUserId": "usr_trade_examiner_001",
  "examinationStartedAt": "2024-01-15T09:00:00Z"
}

Accept Presentation

POST /api/v1/trade/presentations/{id}/accept

Accepts a compliant presentation and triggers payment or deferred payment.

Request Body:

{
  "acceptanceNotes": "All documents comply with LC terms and UCP 600",
  "paymentDueDate": "2024-04-15",
  "maturityDate": "2024-04-15"
}

Response:

{
  "data": {
    "id": "pres_xyz789",
    "status": "accepted",
    "acceptanceDate": "2024-01-15",
    "paymentDueDate": "2024-04-15",
    "paymentAmount": { "amount": 450000, "currency": "USD" },
    "updatedAt": "2024-01-15T14:00:00Z"
  }
}

Reject Presentation

POST /api/v1/trade/presentations/{id}/reject

Refuses a discrepant presentation under UCP 600 Article 16.

Request Body:

{
  "refusalNotice": "Documents refused for the following reasons",
  "disposition": "holding_pending_instructions",
  "discrepancyIds": ["disc_001", "disc_002"],
  "noticeSentAt": "2024-01-16T10:00:00Z"
}

Get Presentation Discrepancies

GET /api/v1/trade/presentations/{id}/discrepancies

Lists all identified discrepancies for a presentation.

Response:

{
  "data": [
    {
      "id": "disc_001",
      "presentationId": "pres_xyz789",
      "documentType": "commercial_invoice",
      "discrepancyCode": "AMOUNT_MISMATCH",
      "description": "Invoice amount USD 450,000 does not match LC amount USD 445,000",
      "severity": "blocking",
      "status": "open",
      "identifiedAt": "2024-01-15T11:00:00Z"
    },
    {
      "id": "disc_002",
      "presentationId": "pres_xyz789",
      "documentType": "bill_of_lading",
      "discrepancyCode": "LATE_SHIPMENT",
      "description": "Shipment date 15 Jan 2024 is after latest shipment date 10 Jan 2024",
      "severity": "blocking",
      "status": "open",
      "identifiedAt": "2024-01-15T11:05:00Z"
    }
  ]
}

Resolve Discrepancy

POST /api/v1/trade/discrepancies/{id}/resolve

Resolves a discrepancy, either by waiver or corrected document.

Request Body:

{
  "resolutionType": "applicant_waiver",
  "waiverReference": "WAIVER-2024-001",
  "resolvedBy": "usr_trade_manager_001",
  "resolvedAt": "2024-01-16T09:00:00Z",
  "notes": "Applicant has accepted the discrepancy under waiver"
}

LC Status Reference

LC Status	Description
`draft`	LC application created, pending submission
`submitted`	Submitted to issuing bank for approval
`approved`	Approved, pending issuance
`issued`	LC issued and transmitted to advising/confirming bank
`amended`	LC amended with applicant/beneficiary agreement
`expired`	LC past expiry date, no further presentations allowed
`cancelled`	LC cancelled prior to expiry

Presentation Lifecycle

stateDiagram-v2
    direction LR

    [*] --> Received: Present Documents
    Received --> UnderReview: Initiate Examination
    UnderReview --> Accepted: Compliant Documents
    UnderReview --> Discrepant: Discrepancies Found
    Discrepant --> Accepted: Discrepancies Waived
    Discrepant --> Rejected: Refusal Issued
    Accepted --> SettlementInitiated: Trigger Payment
    SettlementInitiated --> Settled: Payment Completed

    classDef received fill:#1565c0,color:#fff,stroke:#1565c0
    classDef review fill:#e65100,color:#fff,stroke:#e65100
    classDef discrepant fill:#f57f17,color:#fff,stroke:#f57f17
    classDef accepted fill:#2e7d32,color:#fff,stroke:#2e7d32
    classDef settled fill:#1a5f4a,color:#fff,stroke:#1a5f4a
    classDef rejected fill:#c62828,color:#fff,stroke:#c62828

    class Received received
    class UnderReview review
    class Discrepant discrepant
    class Accepted accepted
    class SettlementInitiated accepted
    class Settled settled
    class Rejected rejected

Discrepancy Codes

Code	Description
`AMOUNT_MISMATCH`	Document amount differs from LC or other document amount
`LATE_PRESENTATION`	Documents presented after expiry or latest presentation date
`LATE_SHIPMENT`	Shipment date after latest shipment date in LC
`INCOMPLETE_DOCUMENTS`	Required documents missing from presentation
`DESCRIPTION_MISMATCH`	Goods description does not match LC terms
`PORT_MISMATCH`	Port of loading/discharge differs from LC terms
`ENDORSEMENT_MISSING`	Required endorsements absent on transport documents
`PARTIAL_SHIPMENT`	Partial shipment when LC prohibits it

Webhooks

The Trade Finance Rail emits the following webhook events:

Event	Description
`trade.lc.created`	LC application created
`trade.lc.submitted`	LC submitted to issuing bank
`trade.lc.approved`	LC approved
`trade.lc.issued`	LC issued and transmitted
`trade.presentation.received`	Documentary presentation received
`trade.presentation.reviewed`	Examination completed
`trade.presentation.accepted`	Presentation accepted, payment triggered
`trade.presentation.rejected`	Presentation refused
`trade.discrepancy.opened`	Discrepancy identified during examination
`trade.discrepancy.resolved`	Discrepancy resolved (waiver or correction)
`trade.settlement.initiated`	Settlement/payment triggered for accepted docs
`trade.settlement.completed`	Settlement completed

Code Examples

import { IOFClient } from "@iof/sdk";

const client = new IOFClient({ apiKey: process.env.IOF_API_KEY });

// Create a trade presentation under an existing LC
const presentation = await client.trade.presentations.create({
  lcId: "lc_abc123",
  presentingBankBic: "RIBLSARIXXX",
  presentationDate: "2024-01-15",
  documents: [
    {
      type: "commercial_invoice",
      documentNumber: "INV-2024-001",
      documentDate: "2024-01-12",
      amount: { amount: 450000, currency: "USD" },
      fileReference: "file_doc_001",
    },
    {
      type: "bill_of_lading",
      documentNumber: "BL-2024-001",
      documentDate: "2024-01-13",
      portOfLoading: "AEJEA",
      portOfDischarge: "SAJED",
      fileReference: "file_doc_002",
    },
  ],
  draftAmount: { amount: 450000, currency: "USD" },
});

// Begin examination
await client.trade.presentations.review(presentation.id, {
  examinerUserId: "usr_trade_examiner_001",
});

// Accept compliant presentation
await client.trade.presentations.accept(presentation.id, {
  acceptanceNotes: "All documents comply with LC terms",
  paymentDueDate: "2024-04-15",
});

// Alternatively, check and resolve discrepancies
const discrepancies = await client.trade.presentations.discrepancies(
  presentation.id,
);
for (const disc of discrepancies.data) {
  await client.trade.discrepancies.resolve(disc.id, {
    resolutionType: "applicant_waiver",
    waiverReference: "WAIVER-2024-001",
  });
}

from iof import IOFClient

client = IOFClient(api_key=os.environ["IOF_API_KEY"])

# Create presentation
presentation = client.trade.presentations.create(
    lc_id="lc_abc123",
    presenting_bank_bic="RIBLSARIXXX",
    presentation_date="2024-01-15",
    documents=[
        {
            "type": "commercial_invoice",
            "document_number": "INV-2024-001",
            "amount": {"amount": 450000, "currency": "USD"},
            "file_reference": "file_doc_001",
        }
    ],
    draft_amount={"amount": 450000, "currency": "USD"},
)

# Review and accept
client.trade.presentations.review(presentation.id)
client.trade.presentations.accept(
    presentation.id, acceptance_notes="Documents comply with LC terms"
)

# Retrieve discrepancies if any
discrepancies = client.trade.presentations.discrepancies(presentation.id)

Next Steps

Islamic LC Rail - Letter of Credit issuance
Bank Guarantee Rail - Bank guarantees
Clearing Rail - Transaction clearing
Settlement Rail - Final settlement