Guides/Payment Webhooks

Payment Webhooks

These webhooks notify you about outbound transaction lifecycle events in the FV Bank system—from creation to final status updates.

📌 Transaction Event Types

Event Type	Description
`TRANSACTION_CREATED`	Triggered when a transaction is created in the FV Bank system. The payment is not yet processed and requires compliance review before funds transfer begins.
`TRANSACTION_DENIED`	Triggered when a transaction is rejected by the compliance team. The payment will not be processed further.
`TRANSACTION_AUTHORIZED`	Triggered when a transaction receives approval from the compliance team. Some transactions may require multiple approvals before processing.
`TRANSACTION_STATUS`	Triggered when there is an update to the transaction status after funds transfer has been initiated. This includes updates from intermediary or receiving banks.
`TRANSACTION_CANCELLED`	Triggered when a transaction is cancelled by the compliance team before completion.
`TRANSACTION_EXPIRED`	Triggered when a transaction expires due to no action or approval from the compliance team within a defined timeframe.

⚠️ Important Note on `TRANSACTION_STATUS`

The TRANSACTION_STATUS webhook has a different payload structure compared to other transaction events.

It includes status changes from the beneficiary bank side
Should be used to track progress after initiation

📦 Example: Transaction Webhook (All Events Except `TRANSACTION_STATUS`)

code


{
  "Date": "2023-06-15T07:46:18",
  "Data": {
    "CreatedDate": "2023-06-15T07:46:18.150Z",
    "TransactionNumber": "FV000017423",
    "Type": "Payment - Domestic (ACH)",
    "Amount": "1.00",
    "From": "Rishav_Business - Rishav",
    "To": "Johnie Rogan",
    "Currency": "USD",
    "Description": "Rent payment",
  …

📦 Example: Transaction Status Webhook

code


{
  "Date": "2022-05-18T07:32:22",
  "Data": {
    "CreatedDate": "2022-05-18T07:30:44.863Z",
    "NewStatus": "COMPLETED",
    "OldStatus": "IN PROCESS",
    "TransactionNumber": "FV000004645",
    "Type": "Payment - Domestic Wire"
  },
  "AdditionalData": [
      { "label": "Routing Number", "value": "026001591" },
  …

🧠 How to Use These Events (Payments)

Use TRANSACTION_CREATED to detect that an outbound payment has been initiated and is awaiting compliance review
Use TRANSACTION_AUTHORIZED to confirm the payment has passed compliance checks and is approved for processing
Use TRANSACTION_STATUS to track real-time updates once funds movement has begun (e.g., processing, completed)
Use TRANSACTION_DENIED, TRANSACTION_CANCELLED, and TRANSACTION_EXPIRED as failure or terminal states requiring attention or retry logic

⚠️ Best Practices

Always verify webhook signatures before processing
Handle duplicate events (idempotency)
Use TransactionNumber to reconcile with your system

📌 Summary

code


Compliance Flow → CREATED → AUTHORIZED / DENIED → CANCELLED / EXPIRED
Execution Flow → STATUS (IN PROCESS → COMPLETED / FAILED)

These webhooks allow you to build real-time tracking and reconciliation for all outbound payments.

Payment Webhooks

📌 Transaction Event Types

⚠️ Important Note on TRANSACTION_STATUS

📦 Example: Transaction Webhook (All Events Except TRANSACTION_STATUS)

📦 Example: Transaction Status Webhook

🧠 How to Use These Events (Payments)

⚠️ Best Practices

📌 Summary

⚠️ Important Note on `TRANSACTION_STATUS`

📦 Example: Transaction Webhook (All Events Except `TRANSACTION_STATUS`)