Skip to main content
VTPE notifies your system about payment state changes through webhook events. Understanding these states helps you build a robust integration that handles payment sessions, confirmations, and failures correctly. This page describes each event, its data fields, and the actions you should take.

​
Payment States

A VTPE payment follows a simple state model:
After a payment is initialized, it will resolve into either a success or fail state. Each transition triggers a webhook event delivered to your Webhook URL.

​
Event Summary

​
payment.initialized

Create a pending order record in your system. Record the paymentId so you can correlate later events. Do NOT fulfill the order yet; the payment has not been confirmed.

​
payment.success

Fulfill the order and record the paymentId and channel. Send a receipt or confirmation to the customer. Update any inventory or booking systems associated with the reference. The paidAt timestamp tells you exactly when the payment was confirmed.

​
payment.fail

Release any inventory or reservation holds tied to the reference. Update the order status to failed or cancelled. Optionally notify the customer so they can retry or try a different payment method.

​
Channel Values

The payment.success event includes a channel field that indicates which fulfillment channel handled the payment. The possible values are:
Use paymentId as an idempotency key when processing webhooks. VTPE may retry webhook delivery, so handle duplicate events safely to avoid double fulfillment.

​
When Webhooks Do Not Arrive

VTPE makes best-effort webhook delivery, but failures can happen. If a webhook for a reference never arrives, use the Payment Status API to query the current state directly:
  • Check payment.webhookDelivery in the response: if it is fail or pending, the webhook was likely never received.
  • Branch on stage or locked to decide whether to fulfill, hold, or release the associated product.
  • Call the endpoint when you need a decision, not on a continuous polling loop.