# 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 |

{% hint style="info" %}
Only *successful refunds* trigger this webhook. Failed or pending refunds are not sent.
{% endhint %}

## Example Payload

{% code overflow="wrap" %}

```json
{
  "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": "test@mail.com",
    "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"
  }
}
```

{% endcode %}

## **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