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": "test@zotlo.com",
    "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.

Last updated