Payments Webhook

The Payments Webhook notifies your server whenever a successful payment occurs, including subscription transactions (trial start, initial purchase, renewal, reactivation) and one-time (consumable) purchases.

Use this webhook to sync revenue events, unlock purchased content, log payment activity, and trigger post-purchase workflows (emails, CRM events, fulfillment, etc.).

When This Is Triggered

A callback is sent whenever Zotlo records one of the following successful payment events:

Event Type	Description
trial	A free or paid trial has started
start_paid	A subscription started without trial
trial_to_paid	Trial converted into a paid subscription
renewal	A recurring subscription renewal succeeded
reactive	A canceled subscription was reactivated with a payment
consumable	A one-time purchase was completed

Refunds are not included here — they are handled by the Refunds Webhook.

Example Payload

{
  "queue": {
    "type": "TransactionInsert",
    "eventType": "transaction",
    "requestID": "4fee-9169-a6b45555f89b",
    "createDate": {
      "date": "2024-06-15 11:51:35.807000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 1
  },
  "parameters": {
    "id": "38359",
    "payment_type": "subscription",
    "original_transaction_id": "6kab56hfs773-a25f3ebf8e2f",
    "transaction_id": "ba3325ge3ad6791-49f4-9693-a25f3ebf8e2f",
    "package_id": "weekly_",
    "team_id": 22,
    "app_id": 1,
    "status": "trial",
    "create_date": "2024-06-15 11:51:35",
    "purchase_date": "2024-06-15 11:51:35",
    "original_purchase_date": "2024-06-15 11:51:35",
    "price": "0.00",
    "currency": "USD",
    "country": "US",
    "expire_date": "2024-06-22 11:51:35",
    "subscriber_id": "[email protected]",
    "credit_card": "41111111****1111",
    "refund_price": null,
    "refund_date": null,
    "refund_reason": null,
    "is_refund": "0",
    "provider_id": 2222263,
    "provider_transaction_id": "417705901",
    "provider_status": "mastercard",
    "provider_name": "Credit Card",
    "quantity": 1,
    "package_price": 0,
    "subscription_id": "9292132",
    "custom_parameters": {
      "clientUuid": "0bb45b80-1ff5-42ee-a382-a5ee06e641c9",
      "dataWarehouse": {
        "paymentModule": "generate",
        "siteId": 38,
        "flowId": 600,
        "appId": 7,
        "teamId": 7,
        "acceptPolicy": true,
        "fullName": "test",
        "epinCode": "test1235"
      },
      "utm": {
        "source": null,
        "medium": null,
        "campaign": null,
        "term": null,
        "content": null
      },
      "cardBrand": "mastercard",
      "threeds": "1",
      "installment": "1",
      "bank": "lidio3p"
    },
    "paymentMethod": "creditCard",
    "installment": 1,
    "exchange": {
      "status": false,
      "detail": []
    },
    "coupon_campaign": {
      "isUsedCouponCode": false,
      "code": null,
      "discountType": null,
      "discountValue": null
    },
    "language": "en"
  }
}

Field Reference

queue

Event metadata.

Field	Description
queue.type	Always TransactionInsert
queue.eventType	Always transaction
queue.requestID	Unique webhook delivery ID
queue.createDate	Payment timestamp
queue.appId	Project ID in Zotlo

parameters

Details about the successful payment.

Core Transaction Fields

Field	Description
id	Internal payment record ID
payment_type	subscription or consumable (one-time)
transaction_id	The unique ID used for refunds
original_transaction_id	First transaction in a subscription chain
status	Payment lifecycle event (trial, start_paid, renewal, etc.)
purchase_date	Payment timestamp
expire_date	Next billing date (subscriptions only)
price	Charged amount
currency	Payment currency
country	Country determined via IP
subscriber_id	User email or phone
credit_card	Masked card number
provider_name	Payment provider (e.g., Credit Card, PayPal)
provider_transaction_id	Processor transaction ID
provider_status	Card type, issuer, etc.

Refund-Related Fields

(Always null for payment webhook events, but included for consistency.)

Field	Description
refund_price	Refunded amount (null for non-refund events)
refund_date	Refund date
refund_reason	Reason for refund
is_refund	Always 0 for this webhook

Subscription & Package Fields

Field	Description
package_id	Purchased packageId
package_price	Defined package price
quantity	Units/seats purchased
subscription_id	Subscription ID (0 for one-time purchases)

Custom Metadata

Field	Description
custom_parameters.clientUuid	User session identifier
custom_parameters.dataWarehouse	Internal sales metadata (site, flow, team)
custom_parameters.utm	Campaign data
custom_parameters.epinCode	e-pin code if applicable
custom_parameters.cardBrand	Visa, Mastercard, etc.
custom_parameters.threeds	Whether 3DS was used
custom_parameters.installment	Installment count

Coupon Info

Field	Description
isUsedCouponCode	Indicates coupon usage
code	Coupon code
discountType	Percentage / fixed
discountValue	Discount amount

How To Use This Webhook

Common use cases:

• Grant access to premium features after successful payment

• Log successful transactions in your backend billing system

• Trigger purchase confirmation emails

• Update dashboards or BI pipelines

• Trigger fulfillment (e-pin codes, digital goods)

• Enrich CRM events with revenue details

• Record internal audit logs

Best Practices

• Use transaction_id for all refund operations

• Use payment_type to distinguish between subscriptions & one-time purchases

• Use idempotency on your side: ignore duplicate webhook deliveries

• Always return HTTP 200 once processed successfully