Webhook Events

Detailed payload documentation for all Flintn webhook events.

Event Structure

All webhook events follow this structure:

{
  "event_type": "EVENT_TYPE",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    // Event-specific payload
  }
}

Field

Type

Description

event_type

string

Event type (see below)

event_id

string

Unique event identifier (UUID)

timestamp

string

ISO 8601 timestamp when the event was created

version

string

Webhook payload version (currently "1.0")

data

object

Event-specific payload

Transaction Events

Transaction webhooks contain comprehensive transaction data including customer, card, and risk information.

TRANSACTION_PENDING

Sent when a transaction is created and pending processing.

{
  "event_type": "TRANSACTION_PENDING",
  "event_id": "9877e907-5abd-4120-8b7d-4462f1ac4d3b",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "provider_transaction_id": "JgbRrqgHH",
    "processor": "STRIPE",
    "processor_merchant_id": "5918a342-3ff5-4300-ae94-184e268f99af",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      }
    ],
    "subscription_id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "subscription_plan_name": "Premium Plan",
    "subscription_plan_website_url": "https://example.com/plans",
    "subscription_renewal_retry_attempt": 0,
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 0.00,
    "status": "PENDING",
    "metadata": "{\"key\":\"value\"}",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com",
      "customer_first_name": "John",
      "customer_last_name": "Doe",
      "billing_country": "US"
    },
    "card_data": {
      "card_first_6": "411111",
      "card_last_4": "1111",
      "card_brand": "VISA",
      "card_funding_type": "DEBIT",
      "card_country": "US",
      "cardholder_name": "John Doe",
      "card_exp_month": 12,
      "card_exp_year": 2026,
      "payment_method": "PAYMENT_CARD"
    },
    "bin_data": {
      "bin_number": "411111",
      "issuer_name": "VISA US",
      "issuer_country": "US",
      "issuer_currency": "USD",
      "product_usage_type": "CONSUMER"
    },
    "compliance_data": {
      "three_ds_status": "NOT_PERFORMED"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T10:30:00.123456Z",
    "version": 0,
    "event_id": "9877e907-5abd-4120-8b7d-4462f1ac4d3b"
  }
}

TRANSACTION_AUTHORIZED

Sent when a transaction is successfully authorized.

{
  "event_type": "TRANSACTION_AUTHORIZED",
  "event_id": "272d3651-a408-49d6-a398-33592caf633f",
  "timestamp": "2024-01-15T10:30:05.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "provider_transaction_id": "JgbRrqgHH",
    "processor": "STRIPE",
    "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
    "processor_merchant_id": "5918a342-3ff5-4300-ae94-184e268f99af",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "AUTHORIZED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      }
    ],
    "merchant_order_id": "SUB-92a2d95e-e10c-403b-ab87-b5f476a8b0ed-1770242401",
    "subscription_id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "subscription_plan_name": "Premium Plan",
    "subscription_plan_website_url": "https://example.com/plans",
    "subscription_renewal_retry_attempt": 0,
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 0.00,
    "status": "AUTHORIZED",
    "metadata": "{\"key\":\"value\"}",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com",
      "customer_first_name": "John",
      "customer_last_name": "Doe",
      "billing_country": "US"
    },
    "card_data": {
      "card_first_6": "411111",
      "card_last_4": "1111",
      "card_brand": "VISA",
      "card_funding_type": "DEBIT",
      "card_country": "US",
      "cardholder_name": "John Doe",
      "card_exp_month": 12,
      "card_exp_year": 2026,
      "payment_method": "PAYMENT_CARD"
    },
    "bin_data": {
      "bin_number": "411111",
      "issuer_name": "VISA US",
      "issuer_country": "US",
      "issuer_currency": "USD",
      "product_usage_type": "CONSUMER"
    },
    "compliance_data": {
      "three_ds_status": "NOT_PERFORMED"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T10:30:05.123456Z",
    "version": 1,
    "event_id": "272d3651-a408-49d6-a398-33592caf633f"
  }
}

TRANSACTION_SETTLED

Sent when a transaction is settled and funds transferred.

{
  "event_type": "TRANSACTION_SETTLED",
  "event_id": "6fe45cc8-503c-4d23-a9fd-724a206b3f7a",
  "timestamp": "2024-01-16T08:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "provider_transaction_id": "JgbRrqgHH",
    "processor": "STRIPE",
    "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
    "processor_merchant_id": "5918a342-3ff5-4300-ae94-184e268f99af",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "AUTHORIZED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-16T08:00:00.123456Z",
        "status": "SETTLED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      }
    ],
    "merchant_order_id": "SUB-92a2d95e-e10c-403b-ab87-b5f476a8b0ed-1770242401",
    "subscription_id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "subscription_plan_name": "Premium Plan",
    "subscription_plan_website_url": "https://example.com/plans",
    "subscription_renewal_retry_attempt": 0,
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 0.00,
    "status": "SETTLED",
    "metadata": "{\"key\":\"value\"}",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com",
      "customer_first_name": "John",
      "customer_last_name": "Doe",
      "billing_country": "US"
    },
    "card_data": {
      "card_first_6": "411111",
      "card_last_4": "1111",
      "card_brand": "VISA",
      "card_funding_type": "DEBIT",
      "card_country": "US",
      "cardholder_name": "John Doe",
      "card_exp_month": 12,
      "card_exp_year": 2026,
      "payment_method": "PAYMENT_CARD"
    },
    "bin_data": {
      "bin_number": "411111",
      "issuer_name": "VISA US",
      "issuer_country": "US",
      "issuer_currency": "USD",
      "product_usage_type": "CONSUMER"
    },
    "risk_data": {
      "avs_street_result": "NOT_PROVIDED",
      "avs_postal_result": "NOT_PROVIDED",
      "cvc_result": "NOT_PROVIDED"
    },
    "compliance_data": {
      "three_ds_status": "NOT_PERFORMED"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-16T08:00:00.123456Z",
    "settled_at": "2024-01-16T08:00:00.123456Z",
    "version": 2,
    "event_id": "6fe45cc8-503c-4d23-a9fd-724a206b3f7a"
  }
}

TRANSACTION_DECLINED

Sent when a transaction is declined.

{
  "event_type": "TRANSACTION_DECLINED",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2024-01-15T10:30:05.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "processor": "STRIPE",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "DECLINED",
        "amount": 29.99,
        "currency": "USD"
      }
    ],
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 0.00,
    "status": "DECLINED",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com"
    },
    "card_data": {
      "card_first_6": "411111",
      "card_last_4": "1111",
      "card_brand": "VISA",
      "payment_method": "PAYMENT_CARD"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T10:30:05.123456Z",
    "version": 1,
    "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

TRANSACTION_FAILED

Sent when a transaction fails to process (system error, not a decline).

{
  "event_type": "TRANSACTION_FAILED",
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "timestamp": "2024-01-15T10:30:05.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "processor": "STRIPE",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "FAILED",
        "amount": 29.99,
        "currency": "USD"
      }
    ],
    "amount": 29.99,
    "currency": "USD",
    "status": "FAILED",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T10:30:05.123456Z",
    "version": 1,
    "event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

TRANSACTION_VOIDED

Sent when a transaction is voided (cancelled before settlement).

{
  "event_type": "TRANSACTION_VOIDED",
  "event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "timestamp": "2024-01-15T12:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "processor": "STRIPE",
    "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "AUTHORIZED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-15T12:00:00.123456Z",
        "status": "VOIDED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      }
    ],
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 0.00,
    "status": "VOIDED",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com"
    },
    "card_data": {
      "card_last_4": "1111",
      "card_brand": "VISA",
      "payment_method": "PAYMENT_CARD"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T12:00:00.123456Z",
    "version": 2,
    "event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}

TRANSACTION_REFUNDED

Sent when a transaction is fully refunded.

{
  "event_type": "TRANSACTION_REFUNDED",
  "event_id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "timestamp": "2024-01-20T14:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "processor": "STRIPE",
    "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "AUTHORIZED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-16T08:00:00.123456Z",
        "status": "SETTLED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-20T14:00:00.123456Z",
        "status": "REFUNDED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "re_3SxE7CLP6Zw4SRkr1abc123",
        "processor": "STRIPE"
      }
    ],
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 29.99,
    "status": "REFUNDED",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com"
    },
    "card_data": {
      "card_last_4": "1111",
      "card_brand": "VISA",
      "payment_method": "PAYMENT_CARD"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-20T14:00:00.123456Z",
    "version": 3,
    "event_id": "d4e5f6a7-b8c9-0123-def0-123456789abc"
  }
}

TRANSACTION_PARTIALLY_REFUNDED

Sent when a transaction is partially refunded.

{
  "event_type": "TRANSACTION_PARTIALLY_REFUNDED",
  "event_id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd",
  "timestamp": "2024-01-20T14:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "processor": "STRIPE",
    "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
    "history": [
      {
        "created_at": "2024-01-15T10:30:00.123456Z",
        "status": "PENDING",
        "amount": 29.99,
        "currency": "USD"
      },
      {
        "created_at": "2024-01-15T10:30:05.123456Z",
        "status": "AUTHORIZED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-16T08:00:00.123456Z",
        "status": "SETTLED",
        "amount": 29.99,
        "currency": "USD",
        "processor_transaction_id": "pi_3SxE7CLP6Zw4SRkr17SDtu7U",
        "processor": "STRIPE"
      },
      {
        "created_at": "2024-01-20T14:00:00.123456Z",
        "status": "PARTIALLY_REFUNDED",
        "amount": 10.00,
        "currency": "USD",
        "processor_transaction_id": "re_3SxE7CLP6Zw4SRkr1abc123",
        "processor": "STRIPE"
      }
    ],
    "amount": 29.99,
    "currency": "USD",
    "refunded_amount": 10.00,
    "status": "PARTIALLY_REFUNDED",
    "customer_data": {
      "customer_id": "00bafd1e-ba4c-4ed2-a675-7ec7218027c8",
      "customer_email": "john.doe@example.com"
    },
    "card_data": {
      "card_last_4": "1111",
      "card_brand": "VISA",
      "payment_method": "PAYMENT_CARD"
    },
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-20T14:00:00.123456Z",
    "version": 3,
    "event_id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd"
  }
}

Subscription Events

Subscription webhooks contain detailed subscription information including plan details and payment history.

SUBSCRIPTION_ACTIVATED

Sent when a new subscription is activated after successful initial payment.

{
  "event_type": "SUBSCRIPTION_ACTIVATED",
  "event_id": "cb0036a1-1ab1-4b0d-ba01-bcd5ebf2909f",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "version": "1.0",
  "data": {
    "id": "6d6e33a4-1ba0-4bfa-823d-4ec13e7c9511",
    "subscription_plan_id": "6d2e02e5-9a4d-4b32-b1a1-1e13afa81975",
    "merchant_id": "4a2996f9-4c6f-4f72-8138-7d25da2592c3",
    "customer_id": "35820",
    "order_id": "ORD-35820-001",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "ACTIVE",
    "term_number": 0,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-15T10:30:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "next_charge_at": "2024-02-15T10:30:00.123456Z",
    "trial": false,
    "created_by": "system",
    "retry_attempt_count": 0,
    "payment_info": [
      {
        "id": "f6f665af-9885-4710-848b-2862f10c8225",
        "payment_id": "b02b5f0e-8642-4d33-88a1-b94a76698b82",
        "transaction_id": "bfecbbd1-f181-4ddb-879d-2d7c3d66b8e9",
        "currency": "USD",
        "amount": 49.95,
        "status": "AUTHORIZED",
        "provider": "STRIPE",
        "created_at": "2024-01-15T10:30:00.123456Z"
      }
    ],
    "event_id": "cb0036a1-1ab1-4b0d-ba01-bcd5ebf2909f"
  }
}

SUBSCRIPTION_RENEWED

Sent when a subscription successfully renews for a new billing period.

{
  "event_type": "SUBSCRIPTION_RENEWED",
  "event_id": "575835dd-7afc-45a6-91b5-9f38742e1e4d",
  "timestamp": "2024-02-15T10:30:00.123Z",
  "version": "1.0",
  "data": {
    "id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "customer_id": "cust-1770155937821",
    "order_id": "ORD-1770155937821-001",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "ACTIVE",
    "term_number": 1,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-02-15T10:30:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "next_charge_at": "2024-03-15T10:30:00.123456Z",
    "trial": false,
    "created_by": "system",
    "retry_attempt_count": 0,
    "subscription_plan": {
      "id": "5af965c7-907b-4e0f-9135-848021545673",
      "name": "Premium Plan",
      "website_url": "https://example.com/plans",
      "type": "SUBSCRIPTION_NO_TRIAL",
      "currency": "USD",
      "full_price_amount": 29.99,
      "billing_frequency_value": 1,
      "billing_frequency_unit": "MONTHS",
      "retry_strategy_id": 20,
      "settlement_interval_hours": 1,
      "status": "ACTIVE",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-02-15T10:30:00Z",
      "created_by": "admin@example.com",
      "active_subscriptions_count": 150
    },
    "product_url": "https://example.com/plans",
    "payment_info": [
      {
        "id": "24bfc6cd-2f27-469b-83e0-f0ee48f016a5",
        "payment_id": "dea7277b-7ca2-472e-995b-71adc313a0f3",
        "transaction_id": "c419f8af-6644-482a-a93d-699b91a6f5d8",
        "currency": "USD",
        "amount": 29.99,
        "status": "SETTLED",
        "provider": "STRIPE",
        "created_at": "2024-01-15T10:30:00.123456Z"
      }
    ],
    "event_id": "575835dd-7afc-45a6-91b5-9f38742e1e4d"
  }
}

SUBSCRIPTION_CANCELLED

Sent when a subscription is cancelled immediately.

{
  "event_type": "SUBSCRIPTION_CANCELLED",
  "event_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "timestamp": "2024-01-20T15:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "customer_id": "cust-1770155937821",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "CANCELLED",
    "term_number": 1,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-20T15:00:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "cancellation_date": "2024-01-20T15:00:00.123456Z",
    "next_charge_at": null,
    "trial": false,
    "cancellation_type": "IMMEDIATE",
    "cancellation_reason_code": "CLIENT_REQUESTED",
    "created_by": "system",
    "retry_attempt_count": 0,
    "subscription_plan": {
      "id": "5af965c7-907b-4e0f-9135-848021545673",
      "name": "Premium Plan",
      "website_url": "https://example.com/plans",
      "type": "SUBSCRIPTION_NO_TRIAL",
      "currency": "USD",
      "full_price_amount": 29.99,
      "billing_frequency_value": 1,
      "billing_frequency_unit": "MONTHS",
      "status": "ACTIVE"
    },
    "payment_info": [],
    "event_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde"
  }
}

SUBSCRIPTION_CANCELLATION_SCHEDULED

Sent when a subscription cancellation is scheduled for the end of the current billing cycle.

{
  "event_type": "SUBSCRIPTION_CANCELLATION_SCHEDULED",
  "event_id": "12a3b4c5-d6e7-8901-f234-567890abcdef",
  "timestamp": "2024-01-20T15:00:00.123Z",
  "version": "1.0",
  "data": {
    "id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "customer_id": "cust-1770155937821",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "CANCELLATION_PENDING",
    "term_number": 1,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-01-20T15:00:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "cancellation_date": "2024-01-20T15:00:00.123456Z",
    "effective_end_at": "2024-02-15T10:30:00.123456Z",
    "next_charge_at": null,
    "trial": false,
    "cancellation_type": "END_OF_CYCLE",
    "cancellation_reason_code": "CLIENT_REQUESTED",
    "created_by": "system",
    "retry_attempt_count": 0,
    "subscription_plan": {
      "id": "5af965c7-907b-4e0f-9135-848021545673",
      "name": "Premium Plan",
      "website_url": "https://example.com/plans",
      "type": "SUBSCRIPTION_NO_TRIAL",
      "currency": "USD",
      "full_price_amount": 29.99,
      "billing_frequency_value": 1,
      "billing_frequency_unit": "MONTHS",
      "status": "ACTIVE"
    },
    "payment_info": [],
    "event_id": "12a3b4c5-d6e7-8901-f234-567890abcdef"
  }
}

SUBSCRIPTION_EXPIRED

Sent when a subscription expires (after failed retries or end of term).

{
  "event_type": "SUBSCRIPTION_EXPIRED",
  "event_id": "a7b8c9d0-e1f2-3456-0123-456789abcdef",
  "timestamp": "2024-02-15T10:30:00.123Z",
  "version": "1.0",
  "data": {
    "id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "customer_id": "cust-1770155937821",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "EXPIRED",
    "term_number": 1,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-02-15T10:30:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "expired_at": "2024-02-15T10:30:00.123456Z",
    "next_charge_at": null,
    "trial": false,
    "cancellation_reason_code": "PAYMENT_DECLINED_RETRY_EXHAUSTED",
    "created_by": "system",
    "retry_attempt_count": 5,
    "last_retry_at": "2024-02-14T10:30:00.123456Z",
    "subscription_plan": {
      "id": "5af965c7-907b-4e0f-9135-848021545673",
      "name": "Premium Plan",
      "type": "SUBSCRIPTION_NO_TRIAL",
      "currency": "USD",
      "full_price_amount": 29.99
    },
    "payment_info": [],
    "event_id": "a7b8c9d0-e1f2-3456-0123-456789abcdef"
  }
}

SUBSCRIPTION_BILLING_RETRY

Sent when a billing retry attempt is made for a failed payment.

{
  "event_type": "SUBSCRIPTION_BILLING_RETRY",
  "event_id": "b8c9d0e1-f234-5678-1234-56789abcdef0",
  "timestamp": "2024-02-22T10:30:00.123Z",
  "version": "1.0",
  "data": {
    "id": "92a2d95e-e10c-403b-ab87-b5f476a8b0ed",
    "subscription_plan_id": "5af965c7-907b-4e0f-9135-848021545673",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "customer_id": "cust-1770155937821",
    "email": "john.doe@example.com",
    "payment_method": "PAYMENT_CARD",
    "status": "BILLING_RETRY",
    "term_number": 1,
    "created_at": "2024-01-15T10:30:00.123456Z",
    "updated_at": "2024-02-22T10:30:00.123456Z",
    "start_date": "2024-01-15T10:30:00.123456Z",
    "next_charge_at": "2024-02-25T10:30:00.123456Z",
    "trial": false,
    "created_by": "system",
    "retry_attempt_count": 2,
    "last_retry_at": "2024-02-22T10:30:00.123456Z",
    "next_retry_at": "2024-02-25T10:30:00.123456Z",
    "subscription_plan": {
      "id": "5af965c7-907b-4e0f-9135-848021545673",
      "name": "Premium Plan",
      "type": "SUBSCRIPTION_NO_TRIAL",
      "currency": "USD",
      "full_price_amount": 29.99,
      "retry_strategy_id": 20
    },
    "payment_info": [
      {
        "id": "retry-payment-id",
        "payment_id": "retry-external-id",
        "transaction_id": "retry-transaction-id",
        "currency": "USD",
        "amount": 29.99,
        "status": "DECLINED",
        "provider": "STRIPE",
        "created_at": "2024-02-22T10:30:00.123456Z",
        "decline_code": "insufficient_funds",
        "retry_number": 2
      }
    ],
    "event_id": "b8c9d0e1-f234-5678-1234-56789abcdef0"
  }
}

Transaction Data Field Reference

Core Fields

Field

Type

Description

id

UUID

Unique transaction identifier

payment_id

UUID

Associated payment identifier

merchant_id

UUID

Merchant identifier

amount

decimal

Transaction amount

currency

string

ISO 4217 currency code (e.g., "USD")

status

string

Transaction status

refunded_amount

decimal

Total amount refunded

description

string

Transaction description

descriptor

string

Transaction descriptor shown on statements

metadata

string

Additional transaction metadata as JSON

initiation_type

string

Payment initiation type (ECOMMERCE, SUBSCRIPTION_FIRST_TIME, SUBSCRIPTION_RENEWAL, UNSCHEDULED)

created_at

timestamp

When the transaction was created

updated_at

timestamp

When the transaction was last updated

settled_at

timestamp

When the transaction was settled (if applicable)

settle_after

timestamp

Scheduled automatic capture timestamp

version

integer

Optimistic locking version

Processor Fields

Field

Type

Description

processor

string

Payment processor (e.g., "STRIPE", "PRIMER")

processor_transaction_id

string

Processor's transaction ID

processor_merchant_id

string

Processor's merchant account ID

provider_transaction_id

string

External provider transaction ID

History

The history field contains a chronological array of status transitions throughout the transaction lifecycle. Each entry records a state change with the following fields:

Field

Type

Description

history[].created_at

timestamp

When this status transition occurred

history[].status

string

Transaction status at this point

history[].amount

decimal

Amount associated with this transition (e.g., refund amount)

history[].currency

string

ISO 4217 currency code

history[].processor_transaction_id

string

Processor-specific transaction ID for this transition

history[].processor

string

Payment processor name for this transition

Subscription Fields

Field

Type

Description

subscription_id

UUID

Associated subscription ID

subscription_plan_id

UUID

Subscription plan ID

subscription_plan_name

string

Plan name

subscription_plan_website_url

string

Plan website URL

subscription_type

string

Plan type (ONE_TIME, SUBSCRIPTION_NO_TRIAL, SUBSCRIPTION_FREE_TRIAL, SUBSCRIPTION_PAID_TRIAL)

subscription_renewal_retry_attempt

integer

Retry attempt number (null=non-renewal, 0=initial, 1+=retry)

Customer Data

Field

Type

Description

customer_data.customer_id

string

Merchant-provided customer identifier

customer_data.customer_email

string

Customer email address

customer_data.customer_mobile

string

Customer mobile phone number

customer_data.customer_first_name

string

Customer first name

customer_data.customer_last_name

string

Customer last name

customer_data.day_of_birth

date

Customer date of birth

customer_data.billing_country

string

Billing address country code (ISO 3166-1 alpha-2)

customer_data.billing_postal_code

string

Billing address postal code

customer_data.national_document_id

string

National ID or document number

customer_data.payer_email

string

Payer email if different from customer

customer_data.payer_first_name

string

Payer first name if different from customer

customer_data.payer_last_name

string

Payer last name if different from customer

Card Data

Field

Type

Description

card_data.card_first_6

string

First 6 digits (BIN)

card_data.card_last_4

string

Last 4 digits

card_data.card_fingerprint_hash

string

Hashed card fingerprint for deduplication

card_data.card_brand

string

Card brand (VISA, MASTERCARD, etc.)

card_data.card_funding_type

string

DEBIT, CREDIT, PREPAID

card_data.card_country

string

Card issuing country code (ISO 3166-1 alpha-2)

card_data.cardholder_name

string

Cardholder name

card_data.card_exp_month

integer

Expiration month (1-12)

card_data.card_exp_year

integer

Expiration year (4 digits)

card_data.payment_method

string

Payment method type (PAYMENT_CARD, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANK_ACCOUNT)

card_data.payment_type

string

Payment type classification

card_data.card_token

string

Tokenized card reference

card_data.token_provider

string

Token provider name

card_data.network_token

string

Network tokenization reference

card_data.digital_wallet_type

string

Digital wallet type (APPLE_PAY, GOOGLE_PAY, etc.)

card_data.card_auth_method

string

Card authentication method used

BIN Data

Field

Type

Description

bin_data.bin_number

string

Bank Identification Number

bin_data.bin_range

string

BIN range identifier

bin_data.issuer_name

string

Issuing bank name

bin_data.issuer_country

string

Issuing country code (ISO 3166-1 alpha-2)

bin_data.issuer_currency

string

Issuer currency (ISO 4217)

bin_data.card_level

string

Card level (CLASSIC, GOLD, PLATINUM, etc.)

bin_data.card_category

string

Card category classification

bin_data.product_usage_type

string

CONSUMER, BUSINESS

bin_data.is_regulated

boolean

Whether the card is regulated (Durbin Amendment)

Risk Data

Field

Type

Description

risk_data.avs_street_result

string

AVS street verification result (MATCHED, NOT_MATCHED, NOT_VERIFIED, NOT_PROVIDED, NOT_APPLICABLE, SKIPPED)

risk_data.avs_postal_result

string

AVS postal verification result

risk_data.cvc_result

string

CVC verification result

risk_data.risk_score

decimal

Overall risk score (0.0-100.0)

risk_data.fraud_score

decimal

Fraud detection score (0.0-100.0)

risk_data.decline_code

string

Decline reason code if transaction was declined

risk_data.liability_shift

boolean

Whether liability shift occurred (3DS)

Compliance Data

Field

Type

Description

compliance_data.three_ds_version

string

3D Secure protocol version used

compliance_data.three_ds_status

string

3D Secure authentication status

compliance_data.three_ds_eci

string

Electronic Commerce Indicator from 3DS

compliance_data.cavv

string

Cardholder Authentication Verification Value

compliance_data.xid

string

3D Secure transaction identifier

compliance_data.sca_exemption

string

Strong Customer Authentication exemption type

compliance_data.sca_indicator

string

SCA requirement indicator

compliance_data.moto

boolean

Mail Order/Telephone Order transaction flag

Network Data

Field

Type

Description

network_data.network_transaction_id

string

Payment network transaction identifier

network_data.authorization_code

string

Authorization code from network

network_data.preferred_network

string

Preferred payment network for routing

network_data.actual_network

string

Actual payment network used

network_data.network_token_used

boolean

Whether network tokenization was used

network_data.token_requestor_id

string

Token requestor identifier for network tokens

Processing Data

Field

Type

Description

processing_data.acquirer_name

string

Acquiring bank name

processing_data.processor_name

string

Payment processor name

processing_data.processing_fee

decimal

Processing fee amount

processing_data.interchange_fee

decimal

Interchange fee amount

processing_data.gateway_fee

decimal

Gateway fee amount

processing_data.retry_count

integer

Number of retry attempts

processing_data.processing_time_ms

integer

Processing time in milliseconds

Traffic Data

Field

Type

Description

traffic_data.traffic_source

string

Traffic source identifier

traffic_data.website

string

Website or application identifier

traffic_data.ip_address

string

Customer IP address

traffic_data.ip_country

string

IP-based country code (ISO 3166-1 alpha-2)

traffic_data.ip_city

string

IP-based city name

traffic_data.geo_city

string

Geolocation-based city name

traffic_data.geo_country

string

Geolocation-based country code

Routing Data

Field

Type

Description

routing_data.bank_mid

string

Bank Merchant ID

routing_data.mid_descriptor

string

Merchant descriptor for statements

routing_data.route_id

string

Payment route identifier

routing_data.segment_id

string

Customer segment identifier

routing_data.cascade_number

integer

Cascade attempt number for routing

Subscription Data Field Reference

Core Fields

Field

Type

Description

id

UUID

Subscription identifier

subscription_plan_id

UUID

Subscription plan ID

merchant_id

UUID

Merchant identifier

customer_id

string

Customer identifier

order_id

string

Order identifier

email

string

Customer email address

payment_method

string

Payment method (PAYMENT_CARD, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANK_ACCOUNT)

status

string

Subscription status (ACTIVE, EXPIRED, CANCELLED, BILLING_RETRY, CANCELLATION_PENDING)

term_number

integer

Current billing term number

trial

boolean

Whether subscription is in trial period

product_url

string

Product URL from subscription plan

Timestamps

Field

Type

Description

created_at

timestamp

Subscription creation timestamp

updated_at

timestamp

Last update timestamp

start_date

timestamp

Subscription start date

cancellation_date

timestamp

Cancellation date (if cancelled)

expired_at

timestamp

Expiration timestamp

effective_end_at

timestamp

When subscription access actually ends (for end-of-cycle cancellations)

next_charge_at

timestamp

Next charge timestamp

trial_started_at

timestamp

Trial start timestamp

trial_ends_at

timestamp

Trial end timestamp

pause_start_at

timestamp

Pause start timestamp

pause_end_at

timestamp

Pause end timestamp

Cancellation Fields

Field

Type

Description

cancellation_type

string

IMMEDIATE or END_OF_CYCLE

cancellation_reason_code

string

Reason code (see values below)

cancellation_details

object

Detailed cancellation information

cancellation_details.decline_code

string

Payment decline code

cancellation_details.fraud_case_id

string

Fraud case ID

cancellation_details.fraud_alert_source

string

Source (CB911)

cancellation_details.cancellation_requested_by

string

Person who requested cancellation

cancellation_details.support_case_id

string

Support case ID

cancellation_details.notes

string

Additional context

Cancellation Reason Codes: PAYMENT_HARD_DECLINE, PAYMENT_DECLINED_UNRETRIABLE, PAYMENT_DECLINED_RETRY_EXHAUSTED, MERCHANT_INITIATED, SUSPECTED_FRAUD_ATTEMPT, CHARGEBACK, CLIENT_REQUESTED, DUPLICATED_PAYMENT, SUSPECTED_SCAM_ATTEMPT, OTHER

Retry Fields

Field

Type

Description

retry_attempt_count

integer

Number of retry attempts made

last_retry_at

timestamp

Timestamp of the last retry attempt

next_retry_at

timestamp

Timestamp when the next retry should occur

Subscription Plan Object

Field

Type

Description

subscription_plan.id

UUID

Plan identifier

subscription_plan.name

string

Plan name

subscription_plan.description

string

Plan description

subscription_plan.website_url

string

Plan website URL

subscription_plan.type

string

ONE_TIME, SUBSCRIPTION_NO_TRIAL, SUBSCRIPTION_FREE_TRIAL, SUBSCRIPTION_PAID_TRIAL

subscription_plan.currency

string

ISO 4217 currency code

subscription_plan.full_price_amount

decimal

Full price amount

subscription_plan.billing_frequency_value

integer

Billing frequency value

subscription_plan.billing_frequency_unit

string

DAYS, WEEKS, MONTHS, YEARS

subscription_plan.trial_price_amount

decimal

Trial price amount

subscription_plan.trial_period_value

integer

Trial period value

subscription_plan.trial_period_unit

string

DAYS, WEEKS, MONTHS, YEARS

subscription_plan.retry_strategy_id

integer

Retry strategy ID

subscription_plan.settlement_interval_hours

integer

Settlement interval in hours

subscription_plan.status

string

ACTIVE, DRAFT, DEACTIVATED

subscription_plan.active_subscriptions_count

integer

Count of active subscriptions

Payment Info Array

Field

Type

Description

payment_info[].id

UUID

Payment info record ID

payment_info[].payment_id

string

Payment ID from payment service

payment_info[].transaction_id

UUID

Transaction ID

payment_info[].currency

string

ISO 4217 currency code

payment_info[].amount

decimal

Payment amount

payment_info[].status

string

Payment status

payment_info[].provider

string

Payment provider (PRIMER, STRIPE, ADYEN, YUNO, GATEWAY)

payment_info[].created_at

timestamp

Payment creation timestamp

payment_info[].decline_code

string

Decline code for failed payments

payment_info[].retry_number

integer

Retry attempt number (0 for initial, 1+ for retries)

Handling Events

Event Idempotency

Events may be delivered more than once. Use the event_id field to ensure idempotent processing:

app.post('/webhooks/flintn', async (req, res) => {
  const event = req.body;

  // Check if we've already processed this event
  const processed = await db.events.findOne({ eventId: event.event_id });
  if (processed) {
    return res.status(200).send('OK');
  }

  // Process the event
  await handleEvent(event);

  // Mark as processed
  await db.events.insertOne({ eventId: event.event_id, processedAt: new Date() });

  res.status(200).send('OK');
});

Event Ordering

Events may arrive out of order. Use timestamps and status checks:

async function handleSubscriptionEvent(event) {
  const subscription = await db.subscriptions.findOne({
    subscriptionId: event.data.id
  });

  // Only process if this event is newer
  if (subscription && new Date(event.timestamp) <= subscription.lastEventAt) {
    return; // Skip older event
  }

  // Process event...
}

Event Summary Table

Event

Description

TRANSACTION_PENDING

Transaction pending processing

TRANSACTION_AUTHORIZED

Transaction authorized

TRANSACTION_DECLINED

Transaction declined

TRANSACTION_FAILED

Transaction failed (system error)

TRANSACTION_VOIDED

Transaction voided

TRANSACTION_SETTLED

Transaction settled

TRANSACTION_REFUNDED

Transaction fully refunded

TRANSACTION_PARTIALLY_REFUNDED

Transaction partially refunded

SUBSCRIPTION_ACTIVATED

New subscription activated

SUBSCRIPTION_RENEWED

Subscription renewed for new period

SUBSCRIPTION_CANCELLED

Subscription cancelled

SUBSCRIPTION_CANCELLATION_SCHEDULED

Subscription cancellation scheduled for end of cycle

SUBSCRIPTION_EXPIRED

Subscription expired

SUBSCRIPTION_BILLING_RETRY

Failed payment retry attempt

Next Steps

Configure Webhooks - Set up webhook endpoints
Webhook Secrets - Signature verification

PreviousConfigure Webhooks NextWebhook Secrets

Last updated 1 day ago

hashtagEvent Structure

hashtagTransaction Events

hashtagTRANSACTION_PENDING

hashtagTRANSACTION_AUTHORIZED

hashtagTRANSACTION_SETTLED

hashtagTRANSACTION_DECLINED

hashtagTRANSACTION_FAILED

hashtagTRANSACTION_VOIDED

hashtagTRANSACTION_REFUNDED

hashtagTRANSACTION_PARTIALLY_REFUNDED

hashtagSubscription Events

hashtagSUBSCRIPTION_ACTIVATED

hashtagSUBSCRIPTION_RENEWED

hashtagSUBSCRIPTION_CANCELLED

hashtagSUBSCRIPTION_CANCELLATION_SCHEDULED

hashtagSUBSCRIPTION_EXPIRED

hashtagSUBSCRIPTION_BILLING_RETRY

hashtagTransaction Data Field Reference

hashtagCore Fields

hashtagProcessor Fields

hashtagHistory

hashtagSubscription Fields

hashtagCustomer Data

hashtagCard Data

hashtagBIN Data

hashtagRisk Data

hashtagCompliance Data

hashtagNetwork Data

hashtagProcessing Data

hashtagTraffic Data

hashtagRouting Data

hashtagSubscription Data Field Reference

hashtagCore Fields

hashtagTimestamps

hashtagCancellation Fields

hashtagRetry Fields

hashtagSubscription Plan Object

hashtagPayment Info Array

hashtagHandling Events

hashtagEvent Idempotency

hashtagEvent Ordering

hashtagEvent Summary Table

hashtagNext Steps

Event Structure

Transaction Events

TRANSACTION_PENDING

TRANSACTION_AUTHORIZED

TRANSACTION_SETTLED

TRANSACTION_DECLINED

TRANSACTION_FAILED

TRANSACTION_VOIDED

TRANSACTION_REFUNDED

TRANSACTION_PARTIALLY_REFUNDED

Subscription Events

SUBSCRIPTION_ACTIVATED

SUBSCRIPTION_RENEWED

SUBSCRIPTION_CANCELLED

SUBSCRIPTION_CANCELLATION_SCHEDULED

SUBSCRIPTION_EXPIRED

SUBSCRIPTION_BILLING_RETRY

Transaction Data Field Reference

Core Fields

Processor Fields

History

Subscription Fields

Customer Data

Card Data

BIN Data

Risk Data

Compliance Data

Network Data

Processing Data

Traffic Data

Routing Data

Subscription Data Field Reference

Core Fields

Timestamps

Cancellation Fields

Retry Fields

Subscription Plan Object

Payment Info Array

Handling Events

Event Idempotency

Event Ordering

Event Summary Table

Next Steps