KingPay Logokingpay.Documentation
Merchant API
Merchant APIWebHooks

Subscriptions Webhook

Webhooks related to subscription lifecycle events. These notifications allow your system to react to successful renewals and subscription expirations.

Payment Notification (action = "renew")

Reports incoming payment progress for a subscription using action = "renew" and payment_status (pending, confirmed or completed). A confirmed transfer can still leave the invoice partially paid. Renew access only when the invoice is paid, once per invoice. Early renewal extends the existing paid-through date; an expired or new subscription starts its period at invoice settlement. Later completed notifications do not add another period. Separate paid renewal invoices each add their saved interval, even if the subscription's current plan has changed. Renewal amounts and plan options come from the paid invoice. The option duration is its nominal interval in seconds, not the cumulative subscription age.

JSON payload example (renew, completed) 
{
  "action": "renew",
  "subscription_id": "sub_123",
  "subscription_url": "https://pay.yourdomain.com/subscription/sub_123",
  "subscription_start_date_ts": 1711929600,
  "subscription_end_date_ts": 1714521600,
  "subscription_option_slug": "pro_monthly",
  "subscription_option_duration_ts": 2592000,
  "subscription_option_value": 20.00,
  "subscription_user_id": "42",
  "subscription_user_email": "[email protected]",

  "payment_url": "https://pay.yourdomain.com/pay/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N",
  "payment_redirect_url": "https://example.com/subscription/success?user_id=42",
  "payment_success_token": "8c0d3a9b9a1c4f3e8b1d2c3a4f6e7b1f",
  "payment_currency": "usd",
  "payment_is_paid": 1,

  "payment_paid_amount": 20.00000000,
  "payment_paid_amount_fiat": 20.00,
  "payment_received_amount": 20.00000000,
  "payment_received_amount_fiat": 20.00,
  "payment_paid_coin": "trc20_usdt",
  "payment_exchange_rate": 1.0,
  "payment_txid": "0x321...",
  "payment_address": "TR7NHqjeKQxGTCi8q8zy4pL8otSzgjLj6t",
  "payment_type": "subscription",
  "payment_status": "completed",
  "invoice_status": "paid",
  "confirmations": 20,
  "required_confirmations": 5,
  "uuid": "d4d6cf64-3fda-485d-8c47-6948870058ef"
}

Key fields

  • action — always "renew" for payment notifications.
  • subscription_id — public subscription UID (subscribeUid), returned as token by creation; not the numeric database ID or your external reference.
  • subscription_start_date_ts / subscription_end_date_ts — current billing cycle.
  • subscription_option_slug — subscription plan identifier.
  • subscription_user_id / subscription_user_email — user reference.
  • payment_is_paid — numeric 1 when the whole invoice is paid, otherwise 0.
  • subscription_option_value — requested plan price in payment_currency, a JSON number rounded to two decimals (0 if unavailable). There is no payment_value field.
  • Renewal invoices apply the project's enabled service/network surcharges when issuing a new payment address. The plan price stays unchanged; the customer pays the fixed crypto quote, including applicable fees and a 10% reserve on the network estimate. Later increases in actual network costs do not require another payment.
  • payment_type — always "subscription".
  • payment_paid_amount / payment_paid_amount_fiat — incoming crypto in payment_paid_coin / fiat in payment_currency, before fees. JSON numbers in ordinary currency units; fiat can be null and falls back to the invoice amount when the stored valuation is missing.
  • payment_received_amount / payment_received_amount_fiat — distributed crypto / fiat equivalent after fees. JSON numbers, only at completed; fiat falls back to incoming fiat if the net valuation is missing and can be null.
  • In subscription list/fetch responses, received_fiat instead totals accepted incoming payments before fees as a decimal string (or null when a valuation is unknown). Our commission is not deducted from that total. A 10 USD payment with 0.20 USD total fees means received_fiat: "10" and, with known valuations, payment_received_amount_fiat: 9.8.
  • payment_paid_coin — cryptocurrency used for the renewal.
  • payment_txid — blockchain transaction hash.
  • payment_status — pending, confirmed, or completed. invoice_status describes invoice settlement separately. Renewal is applied once the invoice is paid, not again when distribution completes.

Expiration Notification (action = "expired")

Sent when a subscription reaches its end date and expires. This webhook is triggered even if no renewal payment was made.

Payload example (expired) 
{
  "action": "expired",
  "subscription_id": "sub_123",
  "subscription_url": "https://pay.yourdomain.com/subscription/sub_123",
  "subscription_start_date_ts": 1711929600,
  "subscription_end_date_ts": 1714521600,
  "subscription_option_slug": "pro_monthly",
  "subscription_option_duration_ts": 2592000,
  "subscription_option_value": 20.00,
  "subscription_user_id": "42",
  "subscription_user_email": "[email protected]",
  "subscription_external_id": "12345",
  "uuid": "a953fb70-753b-4d88-b6be-bb80a1d2cbfd"
}

Key fields

  • action — always "expired" for expiration notifications.
  • subscription_id — public subscription UID, matching renewal notifications.
  • subscription_end_date_ts — unix timestamp when the subscription expired.
  • subscription_option_slug — expired plan identifier.
  • subscription_user_id / subscription_user_email — user reference.
  • subscription_external_id — your external subscription reference.
  • No payment-related fields are included.