Refunds Webhook

The Refunds Webhook notifies your server whenever a refund is successfully processed, whether initiated by you (merchant), the system, or the end-user. This includes refunds for both subscription payments and one-time purchases.

Use this webhook to sync refund activity, update user access, record financial adjustments, and keep internal reporting systems accurate.

When This Is Triggered

A callback is sent whenever Zotlo completes one of the following:

Event Type	Description
refund	A refund has been processed successfully

Only successful refunds trigger this webhook. Failed or pending refunds are not sent.

Example Payload

{
  "queue": {
    "type": "TransactionRefund",
    "eventType": "refund",
    "requestID": "bbb3a4bc-93fc-46da-9d35-b2a7db6f2e3c",
    "createDate": {
      "date": "2024-10-25 15:23:48",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 7
  },
  "parameters": {
    "id": 9599,
    "payment_type": "subscription",
    "original_transaction_id": "093b8307-1658-4f94-a9bd-f101748d3c4b",
    "transaction_id": "093b8307-16-a9bd-f101748d3c4b",
    "package_id": "premium2005",
    "team_id": 7,
    "app_id": 7,
    "status": "start_paid",
    "create_date": "2024-10-25 15:23:48",
    "purchase_date": "2024-10-25 15:23:48",
    "original_purchase_date": "2024-10-25 15:23:48",
    "price": "9.99",
    "currency": "USD",
    "country": "US",
    "expire_date": "2024-10-25 15:23:48",
    "subscriber_id": "[email protected]",
    "credit_card": "41111111****1111",
    "refund_price": "9.99",
    "refund_date": "2024-10-25 15:23:48",
    "refund_reason": "",
    "is_refund": 1,
    "provider_id": 2005,
    "provider_transaction_id": "c9d9e426-c3a2-4b5f-ba67-e09618f1d066",
    "provider_status": "visa",
    "provider_name": "Credit Card",
    "comment": null,
    "json_payload": "",
    "quantity": 1,
    "package_price": "9.99",
    "subscription_id": 2005,
    "is_transfer": null,
    "paymentMethod": "creditCard"
  }
}

Field Reference

queue

Metadata about the refund event.

Field	Description
queue.type	Always TransactionRefund
queue.eventType	Always refund
queue.requestID	Unique webhook delivery ID
queue.createDate	Timestamp of the refund
queue.appId	Project ID in Zotlo

parameters

Details about the refunded transaction.

Core Refund Fields

Field	Description
is_refund	Always 1 for this webhook
refund_price	Amount refunded
refund_date	Timestamp of the refund
refund_reason	Reason provided for the refund

Transaction Context

Refund events include the original transaction details so you can fully reconstruct the refund in your system.

Field	Description
transaction_id	Transaction ID that was refunded
original_transaction_id	Initial subscription transaction ID (first purchase)
payment_type	subscription or consumable
status	Transaction type associated with the refunded payment (start_paid, renewal, consumable, etc.)
price	Original payment amount
currency	Original currency
purchase_date	Original payment date
expire_date	Only applies to subscription transactions
package_id	Purchased package
package_price	Package price
quantity	Quantity purchased

User & Provider Info

Field	Description
subscriber_id	Email or phone sent during purchase
country	Country determined via IP
credit_card	Masked card number
provider_name	Payment provider (e.g., Credit Card, PayPal)
provider_transaction_id	ID provided by the payment provider
paymentMethod	Payment method used

Additional Metadata

Field	Description
team_id	Zotlo account ID
app_id	Project ID within the account
custom_parameters	Any custom parameters sent during purchase
json_payload	Provider-specific data (if available)

Recommended Use Cases

• Reverse access to subscription or premium content

• Log refund events in BI, finance, and internal tools

• Update CRM or marketing platforms

• Trigger refund confirmation emails

• Keep internal accounting systems aligned with real refund data

• Sync with tax or invoicing systems

Best Practices

• Always match refunds with transaction_id

• Keep original_transaction_id for subscription histories

• Ensure idempotency → retry-safe processing

• Return HTTP 200 only after saving the event

• Store webhook logs for audit and reconciliation

• Use refund webhook to update entitlement / access rights