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