> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transit Payment Webhooks

Webhook payloads and statuses for transit payment events.

## Overview

Fin sends `transit.payment.status` webhook events to notify you of payment and settlement status changes. All webhook types share the same event structure.

## Event Structure

Every webhook includes an `event` object and a `data` object:

```text theme={null}
{
  "event": {
    "id": "UUID",                          // unique for every event
    "type": "transit.payment.status",      // always the same
    "event_reference_id": "payment_id",    // payment_id as reference
    "created_at": "2025-10-10T15:40:56Z"   // UTC
  },
  "data": { ... }
}
```

## Payment Status Webhooks

Triggered when the payment status changes.

**Statuses:** `PAY_INIT` | `PAY_PROCESS` | `PAY_TIMEOUT` | `PAY_CANCEL` | `PAY_SUCCESS` | `PAY_FAILED`

```text theme={null}
{
  "event": {
    "id": "UUID",
    "type": "transit.payment.status",
    "event_reference_id": "payment_id",
    "created_at": "2025-10-10T15:40:56Z"
  },
  "data": {
    "payment_id": "FIN_PROVIDED_UUID",
    "integration_type": "PASS_THROUGH",
    "status": "PAY_SUCCESS",
    "create_time": 1740748353,
    "quote_id": "FIN_PROVIDED_UUID",
    "payment_info": {
      "trx_hash": "",
      "pay_id": "...",
      "merchant_trade_no": "841e4ba2-...-a2a45de7bd00",
      "amount": "100",
      "status": "PAY_SUCCESS",
      "currency": "USDC",
      "rail": "SOLANA",
      "currency_type": "...",
      "expire_time": 1740751953,
      "payment_time": 1740748353
    }
  }
}
```

> **Note:**
>
> * `payment_info.trx_hash` is null or empty until `PAY_SUCCESS`
> * `payment_info.pay_id` is null or empty for `integration_type: PASS_THROUGH`
> * `payment_info.payment_time` is `0` until `PAY_SUCCESS`

## Settlement Status Webhooks

Triggered when the settlement status changes, after a successful payment.

**Statuses:** `SETTLEMENT_INIT` | `SETTLEMENT_SUCCESS` | `SETTLEMENT_HOLD` | `SETTLEMENT_FAILED`

```text theme={null}
{
  "event": {
    "id": "UUID",
    "type": "transit.payment.status",
    "event_reference_id": "payment_id",
    "created_at": "2025-10-10T15:40:56Z"
  },
  "data": {
    "payment_id": "FIN_PROVIDED_UUID",
    "integration_type": "PASS_THROUGH",
    "status": "SETTLEMENT_INIT",
    "create_time": 1740748353,
    "quote_id": "FIN_PROVIDED_UUID",
    "payment_info": {
      "trx_hash": "",
      "pay_id": "...",
      "merchant_trade_no": "841e4ba2-...-a2a45de7bd00",
      "amount": "100",
      "status": "PAY_SUCCESS",
      "currency": "BTC",
      "rail": "BITCOIN",
      "currency_type": "crypto",
      "expire_time": 1740751953,
      "payment_time": 1740748353
    },
    "settlement_info": {
      "settlement_via": "FEE_RETENTION",
      "wallet_address": "....",
      "currency": "BTC",
      "rail": "BITCOIN",
      "amount": "100",
      "trx_hash": "0x580...",
      "settle_time": 1740748353,
      "status": "SETTLEMENT_INIT",
      "retry_attempts": 0
    }
  }
}
```

> **Note:**
>
> * `settlement_info` is null until `PAY_SUCCESS`
> * `settlement_info.settle_time` is `0` until `SETTLEMENT_SUCCESS`
> * `data.payment_info.trx_hash` is the on-chain deposit hash
> * `data.settlement_info.trx_hash` is the on-chain settlement transaction hash

## Status Flow

```text theme={null}
PAY_INIT → PAY_PROCESS → PAY_SUCCESS → SETTLEMENT_INIT → SETTLEMENT_SUCCESS
                       ↘ PAY_TIMEOUT                   ↘ SETTLEMENT_HOLD
                       ↘ PAY_CANCEL                    ↘ SETTLEMENT_FAILED
                       ↘ PAY_FAILED
```