Transaction Event

Overview

The Transaction webhook event is triggered when a transaction is created or its status changes. Transactions are generated from financial activities and are assigned a specific Status depending on its progress.

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

• Pending
• Failed
• Settled

To configure a Transaction webhook subscription, reference the Webhook Configuration page.

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

Example

Check the GET transactions/:TransactionID 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 endpoint.

{
  "Data": {
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "PublicID": "TX1234567890",
    "Network": "Bitcoin",
    "Created": "2024-04-16T08:00:55Z",
    "Status": "Settled",
    "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",
    "FiatPayment": {
      "Amount": "5000.00",
      "FeeAmount": "50.00",
      "Rate": "49500.00",
      "FiatCurrency": "USD",
      "FiatDepositID": "e1583a74-ab77-583a-ad2f-1c47617d514b",
      "PaymentSystemID": "20250502CHASUS33000123"
    },
    "Orchestration": {
      "RuleID": "RULE123",
      "RuleExecutionID": "EXEC123"
    },
    "AdjustmentFor": {
      "AdjustedTransactionID": "938235a3-3b56-5c8a-aa81-31f57c503d91",
      "AdjustmentID": "39e3b3a5-cac9-5c41-97fc-d4219669451f",
      "Reason": "ExchangeRateCorrection"
    }
  },
  "EventType": "Transaction",
  "EventVersion": 1730205262722,
  "Occurred": "2024-10-29T12:34:23Z",
  "UserID": "ory|jfu84hr7-2228-4j2c-fu0e-fu555bre38p9"
}

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

"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)

"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")

"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")

"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

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

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