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

# Track Payments and Reconcile

> Monitor transaction status, retrieve payment details, and reconcile with Nostro statements.

# Complete Your Integration

Every production payment system needs reliable monitoring and reconciliation. Inventi Payment Platform provides real-time webhooks for status tracking and Nostro statements for end-of-day verification.

<Info>
  **Your reconciliation toolkit:**

  * **Webhooks** for real-time status updates
  * **Transaction APIs** for on-demand queries and backfill
  * **Nostro statements** (CAMT.052/053/054) for end-of-day verification
</Info>

## Webhooks

Receive real-time notifications as transactions progress through the payment lifecycle.

<CardGroup cols={2}>
  <Card title="Transaction Status Change" icon="bell" href="/payments/webhooks/payment-status-change">
    Payment lifecycle notifications
  </Card>

  <Card title="Cancellation Status Change" icon="ban" href="/payments/webhooks/payment-cancellation-status-change">
    Cancellation request updates
  </Card>
</CardGroup>

## Transaction APIs

Query transaction data, retrieve status history, and download evidence documents.

<CardGroup cols={2}>
  <Card title="List Transactions" icon="list" href="/payments/api/accounts/get-transactions-list-v2">
    Search and filter transactions
  </Card>

  <Card title="Get Transaction" icon="magnifying-glass" href="/payments/api/accounts/get-transaction">
    Retrieve full transaction details
  </Card>

  <Card title="Status History" icon="clock-rotate-left" href="/payments/api/accounts/get-transaction-status-history">
    View complete status timeline
  </Card>

  <Card title="Payment PDF" icon="file-pdf" href="/payments/api/accounts/get-payment-details-pdf">
    Generate payment confirmation
  </Card>

  <Card title="XML Messages" icon="code" href="/payments/api/accounts/get-transaction-related-xml-messages">
    Access ISO 20022 messages
  </Card>
</CardGroup>

## Reference Data

<CardGroup cols={2}>
  <Card title="Transaction Types" icon="tags" href="/payments/api/accounts/get-transaction-types">
    Payment type definitions
  </Card>

  <Card title="Transaction Statuses" icon="circle-info" href="/payments/api/accounts/get-transaction-statuses">
    Status code reference
  </Card>
</CardGroup>

## Nostro Statements

Reconcile your records with bank statements in standard CAMT formats.

<CardGroup cols={2}>
  <Card title="Statement Page" icon="file-lines" href="/payments/api/nostro/nostro-account-statements/get-nostro-account-statement-page">
    Retrieve camt.052/053/054 statements
  </Card>

  <Card title="Bulk Export" icon="file-zipper" href="/payments/api/nostro/nostro-account-statements/get-batched-payment-details-zip">
    Download payment archive
  </Card>

  <Card title="Account Balances" icon="wallet" href="/payments/api/nostro/nostro-account-balances/get-nostro-account-balances">
    Current Nostro balances
  </Card>
</CardGroup>

## Business Requirements

<AccordionGroup>
  <Accordion title="Webhooks are the primary source" icon="bell">
    Use the **Transaction Status Change** webhook to update your local transaction state in near real-time. This is your primary signal for all status changes.

    <Info>
      Poll APIs only for reconciliation and recovery scenarios, not for real-time tracking.
    </Info>
  </Accordion>

  <Accordion title="Webhook retry blocks subsequent deliveries" icon="arrow-rotate-right">
    If your webhook endpoint fails, the platform retries until success and can hold subsequent notifications until the blocked one is delivered.

    <Warning>
      Design your receiver for fast `2xx` responses. Process heavy work asynchronously.
    </Warning>
  </Accordion>

  <Accordion title="Webhook processing must be idempotent" icon="clone">
    You may receive the same event more than once due to retries. Upsert by `trx_id` and store status transitions append-only.
  </Accordion>

  <Accordion title="Reconciliation is mandatory" icon="scale-balanced">
    Even with reliable webhooks, implement scheduled reconciliation using:

    * Transaction list API for backfill
    * Nostro statements (camt.052/053/054) for verification
  </Accordion>

  <Accordion title="Keep current status and history" icon="clock-rotate-left">
    Maintain both for different use cases:

    * `current_status` for fast reads and UI display
    * `status_history` for audit trails and investigations
  </Accordion>
</AccordionGroup>

## Architecture Overview

```mermaid actions={true} theme={null}
flowchart LR
  Platform[Payments Platform] -->|Webhooks| Receiver[Your webhook receiver]
  Receiver --> DB[(Your database)]
  Job[Reconciliation job] -->|APIs| Platform
  Job --> DB
  Apps[Your applications] --> DB
```

## Data Architecture

<Tabs>
  <Tab title="Approach">
    | Source            | Use Case                                |
    | ----------------- | --------------------------------------- |
    | Webhooks          | Real-time status updates                |
    | Transaction APIs  | Backfill, investigation, reconciliation |
    | Nostro statements | End-of-day reconciliation, audit        |
  </Tab>

  <Tab title="When to Poll">
    | Scenario             | Recommended Action        |
    | -------------------- | ------------------------- |
    | Normal operation     | Webhooks only             |
    | Missed webhooks      | Transaction list API      |
    | Daily reconciliation | Nostro statements         |
    | Investigation        | Transaction details + XML |
  </Tab>
</Tabs>

## Transaction Statuses

<Tabs>
  <Tab title="Standard Flow">
    | Status          | Description                     |
    | --------------- | ------------------------------- |
    | `Created`       | Transaction initiated           |
    | `To sign`       | Awaiting signature              |
    | `Signed`        | Signature applied               |
    | `Sent to clear` | Delivered to CSM for processing |
    | `Accepted`      | Accepted by clearing            |
    | `Completed`     | Successfully settled            |
  </Tab>

  <Tab title="Error States">
    | Status      | Description           |
    | ----------- | --------------------- |
    | `Cancelled` | Transaction cancelled |
    | `Rejected`  | Transaction rejected  |
  </Tab>

  <Tab title="Instant Payments">
    | Status                 | Description              |
    | ---------------------- | ------------------------ |
    | `Pending confirmation` | Awaiting confirmation    |
    | `Accepted`             | Confirmed and processing |
    | `Completed`            | Settled in seconds       |
  </Tab>
</Tabs>

## Data Model

<AccordionGroup>
  <Accordion title="Core Tables" icon="database">
    <ResponseField name="transactions" type="table" required>
      One row per `trx_id` with current status
    </ResponseField>

    <ResponseField name="transaction_status_history" type="table" required>
      Append-only status transitions with timestamps
    </ResponseField>

    <ResponseField name="webhook_deliveries" type="table">
      Optional audit log of received webhooks
    </ResponseField>

    <ResponseField name="statement_runs" type="table">
      Reconciliation job tracking
    </ResponseField>
  </Accordion>

  <Accordion title="Primary Keys" icon="key">
    | Key             | Source                  | Usage              |
    | --------------- | ----------------------- | ------------------ |
    | `trx_id`        | Platform transaction ID | Primary identifier |
    | `end_to_end_id` | Customer reference      | Secondary lookup   |
  </Accordion>
</AccordionGroup>

## Reconciliation Flow

Run reconciliation on a schedule to catch missed webhooks and verify records against bank statements.

```mermaid actions={true} theme={null}
sequenceDiagram
  autonumber
  participant Platform as Payments Platform
  participant Webhook as Your Webhook
  participant DB as Your Database
  participant Job as Reconciliation Job

  Platform-->>Webhook: Status change
  Webhook->>DB: Upsert transaction
  Webhook-->>Platform: 2xx

  Note over Job: Scheduled (hourly + daily)

  Job->>Platform: GET /v2/transaction/search
  Platform-->>Job: Transaction list
  Job->>DB: Backfill missing records

  Job->>Platform: GET Nostro statement
  Platform-->>Job: camt.052/053/054
  Job->>DB: Mark reconciled
```

## Statement Types

<CardGroup cols={3}>
  <Card title="CAMT.052" icon="clock">
    **Intraday Statement**

    On-demand balance and transaction report
  </Card>

  <Card title="CAMT.053" icon="calendar-day">
    **End-of-Day Statement**

    Daily closing balance and all transactions
  </Card>

  <Card title="CAMT.054" icon="receipt">
    **Notifications**

    Individual debit/credit notifications
  </Card>
</CardGroup>

## Matching Transactions

Match statement entries to platform transactions using these fields in priority order:

<Steps>
  <Step title="trx_id">
    Platform transaction ID — most reliable matching key
  </Step>

  <Step title="end_to_end_id">
    Customer reference — use when trx\_id unavailable
  </Step>

  <Step title="Amount + IBANs + date">
    Fallback matching for edge cases
  </Step>

  <Step title="Remittance info">
    Last resort when other fields don't match
  </Step>
</Steps>

## Integration Checklist

<Steps>
  <Step title="Implement webhook receiver">
    Create an endpoint that responds `2xx` immediately and processes asynchronously
  </Step>

  <Step title="Store transactions with history">
    Maintain current status and append-only status history for each `trx_id`
  </Step>

  <Step title="Build transaction sync">
    Use the List Transactions API for reconciliation and backfill
  </Step>

  <Step title="Enable investigation tools">
    Implement access to transaction details, status history, and XML messages
  </Step>

  <Step title="Schedule reconciliation">
    Run periodic jobs to fetch Nostro statements and verify records
  </Step>
</Steps>

## Ready for Production

With reconciliation in place, you've completed the core integration. Review your work and prepare for go-live:

<CardGroup cols={2}>
  <Card title="Send Payments" icon="paper-plane" href="/payments/outgoing-sepa-payment">
    Review outbound payment flows
  </Card>

  <Card title="Receive Payments" icon="arrow-down" href="/payments/integration-guide/incoming-sepa">
    Review inbound payment handling
  </Card>

  <Card title="Exception Handling" icon="ban" href="/payments/integration-guide/outbound-cancellation">
    Review cancellation and return flows
  </Card>
</CardGroup>