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

# Return Inbound Payments

> Return funds to the originator when you cannot credit the beneficiary account.

# Return Payments You Can't Process

Sometimes you receive payments that can't be credited - closed accounts, compliance blocks, or beneficiary disputes. Inventi handles the return protocol so you can focus on the decision.

<Info>
  **What happens when you return a payment:**

  1. You identify an inbound payment that can't be credited
  2. You submit a return request via API with a reason code
  3. Inventi sends a pacs.004 return message through CSM
  4. Funds are returned to the originating bank
</Info>

## Use Cases

<CardGroup cols={3}>
  <Card title="Account Issues" icon="user-slash">
    Account closed, blocked, or invalid credentials
  </Card>

  <Card title="Compliance" icon="shield-halved">
    AML flags or sanctions screening failures
  </Card>

  <Card title="Disputes" icon="gavel">
    Beneficiary disputes the incoming payment
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Return Transaction" icon="rotate-left" href="/payments/api/sepa/return-transaction-ct">
    Initiate a return for an inbound SEPA CT
  </Card>

  <Card title="Transaction Status Webhook" icon="bell" href="/payments/webhooks/payment-status-change">
    Track return transaction lifecycle
  </Card>

  <Card title="Get Transaction" icon="magnifying-glass" href="/payments/api/accounts/get-transaction">
    Retrieve 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>

## How It Works

When you initiate a return, the platform validates the original transaction, creates a return transaction, and sends a pacs.004 message to the originating bank.

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

  Platform-->>Webhook: Transaction completed (inbound)
  Webhook->>DB: Store inbound transaction

  App->>Platform: POST /v1/transactions/{trx_id}:return
  Platform-->>App: 200 OK

  Platform-->>Webhook: Return created
  Webhook->>DB: Link return to original

  Platform-->>Webhook: Return accepted
  Platform-->>Webhook: Return completed
  Webhook->>DB: Update status
```

## Initiate a Return

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/v1/transactions/{trx_id}:return \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "AC04",
      "additionalInfo": "Account closed"
    }'
  ```
</CodeGroup>

<Info>
  The platform validates that the transaction exists, is inbound, and is eligible for return before processing.
</Info>

## Return Statuses

<Tabs>
  <Tab title="Success Flow">
    | Status      | Description                  |
    | ----------- | ---------------------------- |
    | `Created`   | Return initiated             |
    | `Accepted`  | Clearing system accepted     |
    | `Completed` | Funds returned to originator |
  </Tab>

  <Tab title="Error States">
    | Status     | Description                 |
    | ---------- | --------------------------- |
    | `Rejected` | Return rejected by clearing |
  </Tab>
</Tabs>

## Data Model

Store these fields for complete audit trails:

<ResponseField name="trx_id" type="string" required>
  Original inbound transaction ID
</ResponseField>

<ResponseField name="return_trx_id" type="string">
  Return transaction ID (if separate from original)
</ResponseField>

<ResponseField name="reason" type="string" required>
  Return reason code (ISO 20022)
</ResponseField>

<ResponseField name="status_history" type="array" required>
  Append-only list of status transitions
</ResponseField>

## Integration Checklist

<Steps>
  <Step title="Implement idempotent webhook handler">
    Upsert transactions by ID to handle duplicate deliveries safely
  </Step>

  <Step title="Store return metadata">
    Persist return reason codes and timestamps for compliance
  </Step>

  <Step title="Link related transactions">
    Maintain references between original and return transactions for reporting
  </Step>
</Steps>

## What's Next?

You now understand how to return inbound payments. Complete your exception handling with cancellation flows and reconciliation:

<CardGroup cols={2}>
  <Card title="Cancel Outbound Payments" icon="ban" href="/payments/integration-guide/outbound-cancellation">
    Request cancellation of your outgoing payments
  </Card>

  <Card title="Respond to Cancellations" icon="reply" href="/payments/integration-guide/inbound-cancellation">
    Handle incoming cancellation requests
  </Card>

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