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

# Accept Inbound Payments

> Receive and process incoming SEPA Credit Transfer and Instant payments.

# Receive Payments from Across Europe

When a payment arrives via CSM, Inventi notifies you in real-time through webhooks so you can credit your customer's balance immediately.

<Info>
  **What happens when a payment arrives:**

  1. Payment comes through CSM to your customer's IBAN
  2. Inventi validates and processes the incoming transfer
  3. Your webhook receiver gets notified instantly
  4. You credit your customer's balance in your system
</Info>

## Supported Payment Types

<CardGroup cols={2}>
  <Card title="SEPA Credit Transfer" icon="euro-sign">
    Standard transfers with next business day settlement
  </Card>

  <Card title="SEPA Instant" icon="bolt">
    Real-time payments settled in under 10 seconds
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Transaction Status Webhook" icon="bell" href="/payments/webhooks/payment-status-change">
    Receive notifications for incoming payments
  </Card>

  <Card title="Confirm Transaction" icon="check" href="/payments/api/sepa/inst-payment-confirm-reject">
    Accept or reject pending instant payments
  </Card>

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

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

## Business Requirements

<AccordionGroup>
  <Accordion title="Webhooks are the primary trigger" icon="bell">
    Use the **Transaction Status Change** webhook to create and update incoming transaction records in your system. This is the primary signal for all inbound payments.

    <Info>
      Webhooks provide near real-time notifications. Use polling only as a fallback for reconciliation.
    </Info>
  </Accordion>

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

    <Warning>
      Your webhook receiver must respond with `2xx` quickly. Process heavy work asynchronously using a queue.
    </Warning>
  </Accordion>

  <Accordion title="Pending confirmation is time-critical" icon="stopwatch">
    When Instant Confirmation is enabled, incoming SEPA Instant transactions arrive as `Pending confirmation`. You must respond within **5 seconds** after receiving the webhook.

    <Tip>
      Build an automated decision service. Manual review is not viable with a 5-second deadline.
    </Tip>
  </Accordion>
</AccordionGroup>

## How It Works

The platform sends webhook notifications as transactions progress through the payment lifecycle.

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

  Platform-->>Webhook: Transaction created (inbound)
  Webhook->>DB: Store transaction
  DB-->>UI: Display pending payment

  Platform-->>Webhook: Transaction accepted
  Webhook->>DB: Update status

  Platform-->>Webhook: Transaction completed
  Webhook->>DB: Credit beneficiary account
  DB-->>UI: Show completed payment
```

## Webhook Payload

Each status change notification includes these fields:

<ResponseField name="trx_id" type="integer" required>
  Unique transaction identifier
</ResponseField>

<ResponseField name="end_to_end_id" type="string">
  End-to-end reference from the originator
</ResponseField>

<ResponseField name="direction" type="string" required>
  `INBOUND` for incoming payments
</ResponseField>

<ResponseField name="status" type="string" required>
  Current transaction status
</ResponseField>

<ResponseField name="amount" type="integer" required>
  Amount in cents
</ResponseField>

<ResponseField name="currency" type="string" required>
  Currency code (EUR)
</ResponseField>

<ResponseField name="debtor_iban" type="string">
  Sender's IBAN
</ResponseField>

<ResponseField name="creditor_iban" type="string">
  Recipient's IBAN
</ResponseField>

<ResponseField name="updated_at" type="datetime" required>
  Status change timestamp
</ResponseField>

## Transaction Statuses

<Tabs>
  <Tab title="SCT Inbound">
    | Status      | Description     | Your Action             |
    | ----------- | --------------- | ----------------------- |
    | `Completed` | Ready to credit | Credit customer balance |
  </Tab>

  <Tab title="Instant with Confirmation">
    | Status                 | Description              | Your Action                                                                     |
    | ---------------------- | ------------------------ | ------------------------------------------------------------------------------- |
    | `Created`              | Instant payment received | —                                                                               |
    | `Pending confirmation` | Awaiting your decision   | Accept or reject within 5s                                                      |
    | `Accepted`             | You accepted             | —                                                                               |
    | `Completed`            | Credited                 | Update customer balance                                                         |
    | `Rejected`             | You rejected             | Payment is not settled - the originator is notified via pacs.002; no funds move |
  </Tab>

  <Tab title="Error States">
    | Status     | Description                             |
    | ---------- | --------------------------------------- |
    | `Rejected` | Rejected by your decision or validation |
  </Tab>
</Tabs>

## Handle SEPA Instant Confirmation

When instant confirmation is enabled for your account, incoming SEPA Instant payments require your approval.

```mermaid actions={true} theme={null}
sequenceDiagram
  autonumber
  participant Platform as Payments Platform
  participant Webhook as Your Webhook
  participant App as Decision Service
  participant DB as Your Database

  Platform-->>Webhook: Pending confirmation
  Webhook->>App: Trigger decision (fast)

  alt Accept payment
    App->>Platform: POST /v1/transactions/{id}/response
    Note right of App: {"response":"ACCEPT"}
    Platform-->>Webhook: Transaction accepted
    Platform-->>Webhook: Transaction completed
  else Reject payment
    App->>Platform: POST /v1/transactions/{id}/response
    Note right of App: {"response":"REJECT","rejectReason":"AC01"}
    Platform-->>Webhook: Transaction rejected
  end
```

### Confirmation Endpoint

<CodeGroup>
  ```bash Accept Payment theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/v1/transactions/{id}/response \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{"response": "ACCEPT"}'
  ```

  ```bash Reject Payment theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/v1/transactions/{id}/response \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{"response": "REJECT", "rejectReason": "AC01"}'
  ```
</CodeGroup>

<Warning>
  You must respond within **5 seconds**. The transaction must be in `Pending confirmation` status.
</Warning>

## Decision Patterns

<CardGroup cols={3}>
  <Card title="Auto-accept" icon="robot">
    Accept all payments automatically. Best for low-risk scenarios with trusted counterparties.
  </Card>

  <Card title="Rules-based" icon="scale-balanced">
    Apply amount limits, counterparty checks, and AML screening. Recommended for most use cases.
  </Card>

  <Card title="Manual review" icon="user">
    Human approval required. Not viable due to 5-second time limit.
  </Card>
</CardGroup>

## Integration Checklist

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

  <Step title="Handle idempotency">
    Upsert transactions by `trx_id` to safely handle duplicate deliveries
  </Step>

  <Step title="Process inbound direction">
    Filter for `direction=INBOUND` and update your ledger accordingly
  </Step>

  <Step title="Implement confirmation flow">
    If using instant confirmation, build a fast decision service that responds within 5 seconds
  </Step>

  <Step title="Maintain status history">
    Store all status transitions for audit and investigation purposes
  </Step>
</Steps>

## What's Next?

Your integration now handles both sending and receiving payments. Complete it with exception handling and reconciliation:

<CardGroup cols={2}>
  <Card title="Return Payments" icon="rotate-left" href="/payments/integration-guide/as">
    Return funds when you can't credit the beneficiary
  </Card>

  <Card title="Handle Cancellations" icon="ban" href="/payments/integration-guide/inbound-cancellation">
    Respond when originators request cancellation
  </Card>

  <Card title="Track and Reconcile" icon="chart-line" href="/payments/integration-guide/payment-information">
    Monitor transactions and verify with Nostro statements
  </Card>
</CardGroup>