Payments

Learn how to get payment transactions to your server via webhooks

This webhook service keeps you informed about any successful payment transaction including one-time and subscription based payments.

Setup the Endpoint URL

Webhook events are sent to your server via HTTP POST. You configure the endpoint URL through Developer Tools / Webhooks menu under your project.

Webhook Events Sending Rules

The webhook notification for payments is sent within the first 5 minutes. For the delivery to be considered successful, your system must return an HTTP 200 status code. Any status code other than 200 will be considered a failure, and the following retry process will apply:

• If the delivery fails, the process will be retried after 10 minutes.

• If the second attempt fails, the next three attempts will be made at 30-minute intervals.

• If the delivery still fails after these three attempts, the next retry will occur 1 hour later.

• If this attempt also fails, the process will not be retried, and the process will be terminated.

Events Format

Webhook events are serialized in JSON. The body of a POST request to your server will contain the serialized event.

{
  "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": "TRY",
    "country": "TR",
    "expire_date": "2024-06-22 11:51:35",
    "subscriber_id": "[e-mail]",
    "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",
    "comment": null,
    "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"
  }
}

Fields

Field	Description
queue	It includes information about the webhook type and date.
queue.type	It specifies that the webhook is of the payment type. For this webhook type, it can only take the value of TransactionInsert.
queue.eventType	It is the transaction type information. In this webhook, since only a payment transaction occurs, it can only take the value of transaction.
queue.requestID	It is the unique identifier for the relevant transaction.
queue.createDate	It is the date the transaction occurred.
queue.createDate.timezone_type	It provides information about the types of time zones.
queue.createDate.timezone	It provides information about the time zone.
queue.appId	It is the project ID in the Zotlo account where the sale was made.
parameters	Contains details of the information related to the webhook.
parameters.id	ID corresponding to the relevant transaction in the Zotlo database.
parameters.payment_type	Type of payment transaction. Can be subscription or consumable ( one-time)
parameters.original_transaction_id	Unique ID of the purchase transaction used in refund transactions.
parameters.transaction_id	Unique ID of the purchase transaction used in refund transactions.
parameters.package_id	Id of the package purchased in the transaction.
parameters.team_id	Id of the Zotlo account where the sale was made.
parameters.app_id	Project Id in the Zotlo account where the sale was made.
parameters.status	Contains the transaction types, possible values : trial : A trial started trial_to_paid : Trial converted to paid subscription start_paid : A paid subscription started (no trial package) renewal : Subscription renewed reactive : User reactivated a passive subscription with a payment consumable :Purchased a one-time package
parameters.create_date	Registration date of the payment in Zotlo databases.
parameters.purchase_date	Transaction execution date.
parameters.original_purchase_date	Initial date of the subscription for the subscriber.
parameters.price	Amount of the payment transaction.
parameters.currency	Currency of the payment transaction.
parameters.country	User's country determined by IP address.
parameters.expire_date	Expiry date of the subscription purchase if applicable.
parameters.subscriber_id	ID of the user making the purchase, which could be a phone number or email.
parameters.credit_card	Masked credit card number used in the purchase transaction.
parameters.refund_price	Refund amount. null if it's not a refund transaction.
parameters.refund_date	Refund date.null if it's not a refund transaction.
parameters.refund_reason	Refund reason. null if it's not a refund transaction.
parameters.is_refund	Refund information. 1 indicates a refund, 0 indicates no refund.
parameters.provider_name	Provider information where the transaction occurred.
parameters.quantity	Quantity of the purchased product or service.
parameters.package_price	Price of the purchased package.
parameters.subscription_id	Unique transaction ID of the user making the purchase in Zotlo.
parameters.custom_parameters	Contains information about the user and the sales site.
parameters.custom_parameters.clientUuid	Session ID based on the user.
parameters.custom_parameters.dataWarehouse.paymentModule	Indicates the sales channel. Currently only accepts generate.For users coming from the marketplace, this value will be store.
parameters.custom_parameters.dataWarehouse.siteId	Site ID in Zotlo where the sale was made.
parameters.custom_parameters.dataWarehouse.flowId	Flow ID associated with the site in Zotlo.
parameters.custom_parameters.dataWarehouse.appId	Project ID in the Zotlo account where the sale was made.
parameters.custom_parameters.dataWarehouse.teamId	ID of the Zotlo account where the sale was made.
parameters.custom_parameters.dataWarehouse.acceptPolicy	It indicates whether the user has accepted the legal notifications. If true, they have accepted; if false, they have not accepted.
parameters.custom_parameters.dataWarehouse.fullName	Full name entered by the user.
parameters.custom_parameters.dataWarehouse.epinCode	If there is a package sale of e-pin type, it is the information of the pin code sold to the user.
parameters.custom_parameters.utm	Provides information about UTM parameters.
parameters.custom_parameters.utm.source	UTM parameter indicating the source of site traffic.
parameters.custom_parameters.utm.medium	UTM parameter indicating the type of site traffic.
parameters.custom_parameters.utm.campaign	UTM parameter indicating the campaign.
parameters.custom_parameters.utm.term	UTM parameter indicating the keyword used.
parameters.custom_parameters.utm.content	UTM parameter indicating details of the ad or link content.
parameters.custom_parameters.cardBrand	Indicates the card brand.
parameters.custom_parameters.threeds	Indicates if 3D Secure was used in the payment transaction. 0 = 3DS not used, 1 = 3DS used.
parameters.custom_parameters.installment	Number of installments for the payment. Currently, it receives the value of 1 since only single payment is made.
parameters.paymentMethod	Specifies the payment method.
parameters.installment	Number of installments for the payment. Currently, it receives the value of 1 since only single payment is made.
parameters.exchange.status	Provides information about the exchange rate conversion during the payment. If false, no conversion was applied. If true, conversion was applied.
parameters.exchange.detail	Details of the exchange rate conversion are included.
parameters.coupon_campaign.isUsedCouponCode	This provides information about the usage of the campaign coupon. If false, the coupon code was not used. If true, the coupon code was used.
parameters.coupon_campaign.code	The coupon code used.
parameters.coupon_campaign.discountType	Specifies the type of discount applied for the coupon.
parameters.coupon_campaign.discountValue	The amount of discount applied through the coupon.
parameters.language	User's language.