Webhook Lifecycle Flows
This page describes the sequence of webhooks you will receive for common transaction flows.
Understanding these sequences will help you build robust integrations and properly track the state of customer transactions.
info
Webhook delivery order is not guaranteed. Always use EventVersion to determine the latest state for any given resource.
Status Values
All webhooks use these status values:
| Status | Meaning |
|---|---|
| Pending | Processing in progress |
| Settled | Successfully completed |
| Failed | Did not complete; check for refund information |
Transitions: Pending → Settled OR Pending → Failed
Bank OnRamp (Fiat Deposit → Stablecoin Payout)
When a customer deposits fiat via a Virtual Account (VIBAN) and it triggers a stablecoin purchase and on-chain payout, you will receive at least the following webhooks.
Customer deposits fiat to VIBAN
│
▼
┌─────────────────────────────────────────┐
│ 1. FiatDeposit │
│ Status: "Pending" │
│ ─────────────────────────────────────── │
│ Bank confirmation received. │
│ │
│ Note: May not appear in Sandbox due to │
│ relaxed risk rules. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 2. FiatDeposit │
│ Status: "Settled" │
│ ─────────────────────────────────────── │
│ Risk/KYT approved the deposit. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 3. Transaction (PayIn) │
│ Status: "Pending" │
│ Direction: "In" │
│ Network: "OffNetwork" │
│ ─────────────────────────────────────── │
│ Fiat converted to stablecoin. │
│ Fees calculated (see Breakdown). │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 4. Transaction (PayOut) │
│ Status: "Pending" │
│ Direction: "Out" │
│ Network: "<chain name>" │
│ ─────────────────────────────────────── │
│ On-chain payout initiated. │
│ Network fees deducted. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 5. Transaction (PayIn) │
│ Status: "Settled" │
│ Direction: "In" │
│ ─────────────────────────────────────── │
│ Internal ledger credit confirmed. │
│ (Fast—KYT already done at FiatDeposit) │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 6. Transaction (PayOut) │
│ Status: "Settled" │
│ Direction: "Out" │
│ ─────────────────────────────────────── │
│ On-chain transaction confirmed. │
│ PublicID contains tx hash. │
│ │
│ ✓ FINAL CONFIRMATION │
└─────────────────────────────────────────┘
Summary
| # | EventType | Status | Direction | Network | Meaning |
|---|---|---|---|---|---|
| 1 | FiatDeposit | Pending | — | — | Bank confirmation received |
| 2 | FiatDeposit | Settled | — | — | Risk/KYT approved |
| 3 | Transaction | Pending | In | OffNetwork | Fiat converted to stablecoin |
| 4 | Transaction | Pending | Out | Chain name | On-chain payout initiated |
| 5 | Transaction | Settled | In | OffNetwork | Internal ledger credit confirmed |
| 6 | Transaction | Settled | Out | Chain name | On-chain tx confirmed ✓ |
Example Payloads
Webhook 1 — FiatDeposit (Pending)
{
"Data": {
"Created": "2025-12-04T12:41:06Z",
"CustomerID": "ronaldo-noah-203",
"FiatAmount": "100",
"FiatCurrency": "EUR",
"ID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"PaymentMethodID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodType": "BankSepa",
"Refunds": [],
"Sender": {
"Details": {
"AccountNumber": "MT60SEOUUR41270441818820",
"Type": "FiatPaymentMethodBankDisplay"
}
},
"Status": "Pending"
},
"EventType": "FiatDeposit",
"EventVersion": 1764852066045,
"Occurred": "2025-12-04T12:41:06Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Webhook 2 — FiatDeposit (Settled)
{
"Data": {
"Created": "2025-12-04T12:41:06Z",
"CustomerID": "ronaldo-noah-203",
"FiatAmount": "100",
"FiatCurrency": "EUR",
"ID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"PaymentMethodID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodType": "BankSepa",
"Refunds": [],
"Sender": {
"Details": {
"AccountNumber": "MT60SEOUUR41270441818820",
"Type": "FiatPaymentMethodBankDisplay"
}
},
"Status": "Settled"
},
"EventType": "FiatDeposit",
"EventVersion": 1764852066045,
"Occurred": "2025-12-04T12:41:06Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Webhook 3 — Transaction PayIn (Pending)
{
"Data": {
"Amount": "111.979797",
"Breakdown": [
{ "Amount": "1.13111", "Type": "ChannelFee" },
{ "Amount": "111.979797", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:12Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "In",
"FiatPayment": {
"Amount": "100",
"FeeAmount": "1",
"FiatCurrency": "EUR",
"FiatDepositID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"Rate": "0.8840880389680685"
},
"FiatPaymentMethod": {
"Country": "MT",
"CustomerID": "ronaldo-noah-203",
"DisplayDetails": {
"AccountNumber": "MT60SEOUUR41270441818820",
"BankCode": "CFTEMTM1XXX",
"Type": "FiatPaymentMethodBankDisplay"
},
"ID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodCategory": "Bank"
},
"ID": "4068d70e-c31d-5e3b-959a-f27ea3cc5e1e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764852072100,
"Occurred": "2025-12-04T12:41:12Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Webhook 4 — Transaction PayOut (Pending)
{
"Data": {
"Amount": "107.683104",
"Breakdown": [
{ "Amount": "4.296693", "Type": "NetworkFee" },
{ "Amount": "107.683104", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:14Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "Out",
"ID": "fee2b2a6-0da2-5473-a6a8-eac39cb279d9",
"Network": "EthereumTestSepolia",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764852074748,
"Occurred": "2025-12-04T12:41:14Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Webhook 5 — Transaction PayIn (Settled)
{
"Data": {
"Amount": "111.979797",
"Breakdown": [
{ "Amount": "1.13111", "Type": "ChannelFee" },
{ "Amount": "111.979797", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:12Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "In",
"FiatPayment": {
"Amount": "100",
"FeeAmount": "1",
"FiatCurrency": "EUR",
"FiatDepositID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"Rate": "0.8840880389680685"
},
"FiatPaymentMethod": {
"Country": "MT",
"CustomerID": "ronaldo-noah-203",
"DisplayDetails": {
"AccountNumber": "MT60SEOUUR41270441818820",
"BankCode": "CFTEMTM1XXX",
"Type": "FiatPaymentMethodBankDisplay"
},
"ID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodCategory": "Bank"
},
"ID": "4068d70e-c31d-5e3b-959a-f27ea3cc5e1e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764852079016,
"Occurred": "2025-12-04T12:41:19Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Webhook 6 — Transaction PayOut (Settled)
{
"Data": {
"Amount": "107.683104",
"Breakdown": [
{ "Amount": "4.296693", "Type": "NetworkFee" },
{ "Amount": "107.683104", "Type": "Remaining" }
],
"Created": "2025-12-04T13:00:17Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "Out",
"ID": "fee2b2a6-0da2-5473-a6a8-eac39cb279d9",
"Network": "EthereumTestSepolia",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"PublicID": "mockFireblocks_0158a83c8496379ec8bdd183eb92d9d06576a594df5dcef4e269ccfc6bb4617f",
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764853243442,
"Occurred": "2025-12-04T13:00:44Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}
Crypto OffRamp (On-chain Deposit → Fiat Payout)
When a customer deposits crypto on-chain and it triggers a fiat payout to a beneficiary, you will receive at least the following webhooks.
Customer sends crypto to deposit address
│
▼
┌─────────────────────────────────────────┐
│ 1. Transaction (Crypto Deposit) │
│ Status: "Pending" │
│ Direction: "In" │
│ Network: "<chain name>" │
│ ─────────────────────────────────────── │
│ Crypto deposit received at destination │
│ address. PublicID contains tx hash. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 2. Transaction (Crypto Deposit) │
│ Status: "Settled" │
│ Direction: "In" │
│ ─────────────────────────────────────── │
│ Risk analysis passed. │
│ Crypto deposit confirmed. │
│ │
│ ✓ FUNDS COMMITTED │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 3. Transaction (Fiat Payout) │
│ Status: "Pending" │
│ Direction: "Out" │
│ Network: "OffNetwork" │
│ ─────────────────────────────────────── │
│ Fiat payout initiated to beneficiary. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 4. Transaction (Fiat Payout) │
│ Status: "Settled" │
│ Direction: "Out" │
│ ─────────────────────────────────────── │
│ Bank accepted the payment. │
│ Beneficiary receives funds per channel │
│ settlement time. │
│ │
│ ✓ FINAL CONFIRMATION │
└─────────────────────────────────────────┘
Summary
| # | EventType | Status | Direction | Network | Meaning |
|---|---|---|---|---|---|
| 1 | Transaction | Pending | In | Chain name | Crypto deposit received |
| 2 | Transaction | Settled | In | Chain name | Risk passed, deposit confirmed |
| 3 | Transaction | Pending | Out | OffNetwork | Fiat payout initiated |
| 4 | Transaction | Settled | Out | OffNetwork | Bank accepted payment ✓ |