Skip to main content

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.

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