Skip to main content
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:
{
  "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
{
  "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
{
  "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

PAY_INIT → PAY_PROCESS → PAY_SUCCESS → SETTLEMENT_INIT → SETTLEMENT_SUCCESS
                       ↘ PAY_TIMEOUT                   ↘ SETTLEMENT_HOLD
                       ↘ PAY_CANCEL                    ↘ SETTLEMENT_FAILED
                       ↘ PAY_FAILED