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.

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"
      },
      "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

queue

It includes information about the webhook type and date.

queue.type

It indicates that the webhook is of the payment type.

queue.eventType

It is the transaction type information.

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'.

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

Indicates whether the user has accepted legal disclosures.

parameters.custom_parameters.dataWarehouse.fullName

Full name entered by 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