# Transaction Event

> The Transaction webhook fires when a transaction is created and on every status change, carrying the status that reflects its progress.

## Overview

The `Transaction` webhook event is triggered when a transaction is created or when `Status`, `Refunds`, `SubStatus`, or `RFI` change. Transactions are generated from financial activities and are assigned a specific `Status` depending on progress.

A Transaction can have one the following statuses at a given time:

- `Pending`
- `Failed`
- `Settled`

While `Status` is `Pending`, Noah may also send webhooks as `SubStatus` and/or `RFI` progress. See [SubStatus and RFI](#substatus-and-rfi) below.

To configure a `Transaction` webhook subscription, reference the [Webhook Configuration page](./configuration.md).

## Event Payload Structure

When a `Transaction` event occurs, Noah sends a webhook notification to your configured endpoint with the following JSON Payload; some objects within this are optional depending on the usage from which the transaction was created.

- `Breakdown` - list explaining how the transaction amount should be split
- `DestinationAddress` - on-chain destination wallet address, when applicable (e.g. crypto withdrawals and payouts).
- `FiatPayment` - this object is included if there is a fiat payment method attributed to the transaction.
- `Orchestration` - this object is included if the transaction is a result of a Rule execution.
- `AdjustmentFor` - this object is included if the transaction was created to adjust an earlier transaction.
- `SubStatus` - additional detail while `Status` is `Pending` (omitted when not applicable).
- `RFI` - request-for-information details when compliance has opened an RFI (omitted when none).

### Example

Check the [GET `transactions/:TransactionID`](../../../api-reference/transaction-by-id/) endpoint for available values for each of the parameters. For example, in the payload below, the `Breakdown` Type is set to `BusinessFee`, which could instead be `ChannelFee` or `Remaining`, as documented for the [GET `transactions/:TransactionID`](../../../api-reference/transaction-by-id/) endpoint.

```json
{
  "Data": {
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "PublicID": "TX1234567890",
    "Network": "Bitcoin",
    "Created": "2024-04-16T08:00:55Z",
    "Status": "Pending",
    "SubStatus": "UnderReview",
    "RFI": {
      "Status": "AwaitingCustomer",
      "Type": "Manual"
    },
    "Direction": "In",
    "CustomerID": "550e8400-e29b-41d4-a716-446655440000",
    "ExternalID": "EXT123456",
    "Amount": "12.3",
    "Breakdown": [
      {
        "Amount": "0.1",
        "Type": "BusinessFee"
      },
      {
        "Amount": "12.29",
        "Type": "Remaining"
      }
    ],
    "NetworkFee": "0.0001",
    "CryptoCurrency": "BTC",
    "DestinationAddress": {
      "Address": "bc1qt65af6u9542jhryfpucrfljvk66qwem0ju0y9u"
    },
    "FiatPayment": {
      "Amount": "5000.00",
      "FeeAmount": "50.00",
      "Rate": "49500.00",
      "FiatCurrency": "USD",
      "FiatDepositID": "e1583a74-ab77-583a-ad2f-1c47617d514b",
      "PaymentSystemID": "20250502CHASUS33000123"
    },
    "FiatPaymentMethod": {
      "ID": "Bank/Ach/USD/CHASUS33/1234567890/customer-123",
      "CustomerID": "550e8400-e29b-41d4-a716-446655440000",
      "Country": "US",
      "PaymentMethodCategory": "Bank",
      "DisplayDetails": {
        "Type": "FiatPaymentMethodBankDisplay",
        "AccountNumber": "****6789",
        "BankCode": "CHASUS33"
      },
      "Capabilities": {
        "PayoutTo": true,
        "PayoutFrom": false,
        "PayinTo": true
      },
      "AccountHolderDetails": {
        "Name": {
          "FirstName": "John",
          "LastName": "Doe"
        }
      },
      "IssuerDetails": {
        "Name": "Chase"
      }
    },
    "Orchestration": {
      "RuleID": "RULE123",
      "RuleExecutionID": "EXEC123"
    },
    "AdjustmentFor": {
      "AdjustedTransactionID": "938235a3-3b56-5c8a-aa81-31f57c503d91",
      "AdjustmentID": "39e3b3a5-cac9-5c41-97fc-d4219669451f",
      "Reason": "ExchangeRateCorrection"
    },
    "Refunds": [
      {
        "RefundID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
        "Currency": "USDC_TEST",
        "RefundedAmount": "500",
        "RequestTime": "2025-12-04T14:11:57Z",
        "Status": "Settled"
      }
    ]
  },
  "EventType": "Transaction",
  "EventVersion": 1730205262722,
  "Occurred": "2024-10-29T12:34:23Z",
  "UserID": "ory|jfu84hr7-2228-4j2c-fu0e-fu555bre38p9"
}
```

## SubStatus and RFI

### `SubStatus`

Present only while `Status` is `Pending`. It provides finer detail about where processing is:

| `SubStatus`    | Meaning                                                                              |
| -------------- | ------------------------------------------------------------------------------------ |
| `AmlScreening` | Automatic compliance / KYT (or travel-rule) screening in flight                      |
| `UnderReview`  | Payment placed on hold for transaction-monitoring review                             |
| `Submitted`    | Outbound payment submitted to the external provider                                  |
| `Confirming`   | Outbound payment in progress with the external provider; awaiting final confirmation |

### `RFI`

Present when Noah has opened a request for information on the payment. The object contains:

| Field    | Values                                                   | Meaning                                     |
| -------- | -------------------------------------------------------- | ------------------------------------------- |
| `Status` | `AwaitingCustomer`, `UnderReview`, `Closed`, `Completed` | Where the RFI is in its lifecycle           |
| `Type`   | `Manual`, `ProofOfAddress`                               | What kind of information is being requested |

## Understanding Transaction Webhooks

### Direction Field

The `Direction` field indicates the flow of funds:

| Direction | Meaning                                    |
| --------- | ------------------------------------------ |
| `In`      | Credit — funds entering customer's account |
| `Out`     | Debit — funds leaving customer's account   |

### Network Field

The `Network` field indicates where the transaction occurs:

| Network Value                                               | Meaning                                                         |
| ----------------------------------------------------------- | --------------------------------------------------------------- |
| `OffNetwork`                                                | Internal/off-chain transaction (ledger movement or fiat payout) |
| Chain name (e.g., `EthereumTestSepolia`, `PolygonTestAmoy`) | On-chain blockchain transaction                                 |

### Direction + Network Combinations

| Direction | Network      | What It Represents                              |
| --------- | ------------ | ----------------------------------------------- |
| `In`      | `OffNetwork` | Internal ledger credit (fiat→crypto conversion) |
| `In`      | Chain name   | On-chain crypto deposit received                |
| `Out`     | `OffNetwork` | Fiat payout to bank                             |
| `Out`     | Chain name   | On-chain crypto withdrawal/payout               |

## Nested Object Reference

### Orchestration Object

Present when the transaction is part of an orchestrated flow (rule execution).

| Field             | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `RuleExecutionID` | Links all webhooks in a single flow. Use this to correlate related events. |
| `RuleID`          | The rule that triggered this flow                                          |

```json
"Orchestration": {
  "RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
  "RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
}
```

### FiatPayment Object

Present when the transaction involves fiat currency.

| Field             | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `Amount`          | Fiat amount                                                                |
| `FeeAmount`       | Fees charged                                                               |
| `FiatCurrency`    | Three-letter currency code                                                 |
| `Rate`            | Exchange rate used                                                         |
| `FiatDepositID`   | Links to the originating FiatDeposit (for Bank OnRamp flows)               |
| `PaymentSystemID` | Upstream payment-system ID (e.g., ACH trace number, wire IMAD, SWIFT UETR) |

```json
"FiatPayment": {
  "Amount": "100",
  "FeeAmount": "1",
  "FiatCurrency": "EUR",
  "FiatDepositID": "36c54907-fadd-5a48-91f5-1632253f9a08",
  "Rate": "0.8840880389680685"
}
```

### FiatPaymentMethod Object

Present on fiat payout transactions. Shows the destination for the fiat payment.

| Field                   | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `Country`               | Country code                                           |
| `CustomerID`            | Customer reference                                     |
| `DisplayDetails`        | Account number, TaxID, or other identifier details     |
| `ID`                    | Payment method identifier                              |
| `PaymentMethodCategory` | Category (e.g., "Bank", "Identifier")                  |
| `Capabilities`          | Capability flags (`PayoutTo`, `PayoutFrom`, `PayinTo`) |
| `AccountHolderDetails`  | Account holder metadata (for example holder name)      |
| `IssuerDetails`         | Issuer metadata (for example bank name)                |

```json
"FiatPaymentMethod": {
  "Country": "BR",
  "CustomerID": "74508010-c30b-4c58-a94d-591c281d8630",
  "DisplayDetails": {
    "Identifier": "11184369623",
    "IdentifierType": "TaxID",
    "Type": "FiatPaymentMethodIdentifierDisplay"
  },
  "ID": "Identifier/Pix/BRL/TaxID/...",
  "PaymentMethodCategory": "Identifier"
}
```

### AdjustmentFor Object

Present when this transaction adjusts a previous transaction (e.g., refunds).

| Field                   | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `AdjustedTransactionID` | The original transaction being adjusted                            |
| `AdjustmentID`          | Matches the `RefundID` in the original transaction's Refunds array |
| `Reason`                | Why the adjustment was made (e.g., "Refund")                       |

```json
"AdjustmentFor": {
  "AdjustedTransactionID": "1865092c-d11b-11f0-803f-4a01279ab918",
  "AdjustmentID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
  "Reason": "Refund"
}
```

### Refunds Array

Present on the original transaction when a refund has been initiated.

| Field            | Description                       |
| ---------------- | --------------------------------- |
| `RefundID`       | Unique refund identifier          |
| `Currency`       | Refund currency                   |
| `RefundedAmount` | Amount refunded                   |
| `RequestTime`    | When the refund was requested     |
| `Status`         | `Pending`, `Settled`, or `Failed` |

```json
"Refunds": [
  {
    "RefundID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
    "Currency": "USDC_TEST",
    "RefundedAmount": "500",
    "RequestTime": "2025-12-04T14:11:57Z",
    "Status": "Settled"
  }
]
```

## Compliance Freezes and Refunds for Payouts

For payout flows (crypto → fiat), compliance freezes occur at the **Crypto Settlement** stage. Crypto is received but not converted and paid out until approved.

### Refund Destinations for Payouts

| Funding Method                              | Refund Destination           |
| ------------------------------------------- | ---------------------------- |
| Prefunded dashboard balance                 | Custodian Stablecoin Account |
| Customer crypto deposit (automated payouts) | Sending Crypto Wallet        |

### Transaction Finality

Transactions are processed with finality on `Settled` status. In rare cases, a settled payout can be reversed by a banking-level return. This produces **two** transactions: an internal reversal (`Reverses` field, `OffNetwork`) and a subsequent on-chain crypto return (`AdjustmentFor.Reason=Refund`). The original transaction is not modified.

For the full two-step reversal process with payload examples and linking guidance, see [Compliance Freezes, Refunds & Reversals — Two-Step Reversal Process](../compliance-freezes-refunds-reversals.md#two-step-reversal-process-for-bank-returns).

## Key Questions Answered

| Question                                               | Answer                                                      |
| ------------------------------------------------------ | ----------------------------------------------------------- |
| Which webhook indicates funds are committed? (OffRamp) | Transaction with `Status: "Settled"` and `Direction: "In"`  |
| Which webhook confirms final settlement?               | Transaction with `Status: "Settled"` and `Direction: "Out"` |
| How do I correlate all webhooks in a flow?             | Use `Orchestration.RuleExecutionID`                         |
| How do I link a Transaction to its FiatDeposit?        | Use `FiatPayment.FiatDepositID`                             |
| How do I link a refund to the original transaction?    | Use `AdjustmentFor.AdjustedTransactionID`                   |

## Fields to Store for Reconciliation

| Field                                 | Purpose                                            |
| ------------------------------------- | -------------------------------------------------- |
| `Data.ID`                             | Unique transaction identifier                      |
| `Data.PublicID`                       | On-chain tx hash (when available)                  |
| `Data.ExternalID`                     | Your external reference (set during rule creation) |
| `Data.CustomerID`                     | Link to your customer record                       |
| `Orchestration.RuleExecutionID`       | Correlate all events in a flow                     |
| `FiatPayment.FiatDepositID`           | Link to originating FiatDeposit                    |
| `AdjustmentFor.AdjustedTransactionID` | Link refund to original transaction                |
| `EventVersion`                        | Deduplication and ordering                         |

:::note Note on ExternalID
You can set `ExternalID` when creating orchestration rules via the API. This is recommended for reconciliation. For Crypto OffRamp flows, `ExternalID` may not appear on the initial crypto deposit webhooks (pending system improvement).
:::