Webhooks 🔔

Welcome to our webhooks documentation! This section outlines how the Tranzakt Payment Platform (TPP) delivers webhook notifications to your systems after payment events occur. Our webhook system ensures you receive real-time updates about payment events in your application without needing to poll our API.

Overview

Our webhook system allows you to:

Receive real-time payment notifications

Automate order fulfillment processes

Update customer accounts instantly

Track payment statuses without polling

Implement event-driven architecture

Build reliable payment flows

Webhook Architecture

After a successful payment through the Tranzakt platform, our system sends an HTTP POST request to the callback URL you specified when creating the invoice. This enables your application to react immediately to payment events as they occur.

POST Payment Webhook

Endpoint Setup

To receive webhooks, you need to:

Create a publicly accessible HTTPS endpoint in your application

Specify this endpoint as the webhook when creating an invoice or use deafult webhook on the collection or API settings

Implement proper response handling at your endpoint

Request Details

Method: POST

Content-Type: application/json

Timeout: 30 seconds (requests taking longer will be terminated)

Headers

Header	Value	Description
`Content-Type`	`application/json`	Format of the request body
`Accept`	`application/json`	Expected response format
`User-Agent`	`Tranzakt-Payment-Platform/1.0`	Identifies our platform
`X-Webhook-ID`	UUID string	Unique identifier for the webhook event

Request Body

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "event": "payment.successful",
  "createdAt": "2024-05-20T10:15:30.123Z",
  "data": {
    "id": "22205053-02c7-4607-9cb5-5fa58cecae6d",
    "collectionId": "37a71e2e-ed54-4e46-a3a9-47a211c352ea",
    "collectionName": "Product Sales",
    "title": "Checkout Invoice",
    "amount": 40000,
    "totalAmount": 40400,
    "serviceCharge": 400,
    "vat": 0,
    "payerName": "John Doe",
    "payerEmail": "john.doe@example.com",
    "payerPhoneNumber": "07078955432",
    "billerName": "Example Business",
    "billerEmail": "sales@example.com",
    "billerAddress": "123 Business St",
    "type": "Live",
    "status": "Paid",
    "paymentMethod": "Card",
    "paymentDate": "2024-05-20T10:15:30.123Z",
    "billerMetaData": {
      "order-id": "12345"
    },
    "callBackUrl": "https://your-api.com/webhooks/tranzakt",
    "dateCreated": "2024-05-20T10:00:00.000Z"
  }
}

Request Body Fields

Field	Type	Description
`id`	string	Unique identifier for the webhook notification
`event`	string	Type of event that triggered the webhook (e.g., `payment.successful`)
`createdAt`	string	ISO 8601 timestamp when the webhook was generated
`data`	object	Contains the complete invoice information
`data.id`	string	Invoice ID
`data.collectionId`	string	Collection ID associated with this invoice
`data.collectionName`	string	Name of the collection
`data.title`	string	Invoice title
`data.amount`	number	Base amount in kobo/cents
`data.totalAmount`	number	Total amount including fees in kobo/cents
`data.serviceCharge`	number	Service charge in kobo/cents
`data.vat`	number	VAT amount in kobo/cents
`data.payerName`	string	Name of the payer
`data.payerEmail`	string	Email of the payer
`data.payerPhoneNumber`	string	Phone number of the payer
`data.billerName`	string	Your business name
`data.billerEmail`	string	Your business email
`data.billerAddress`	string	Your business address
`data.type`	string	Invoice type (`Test` or `Live`)
`data.status`	string	Invoice status (will be `Paid` for successful payments)
`data.paymentMethod`	string	Method used for payment (e.g., `Card`, `BankTransfer`)
`data.paymentDate`	string	ISO 8601 timestamp when payment was made
`data.billerMetaData`	object	Custom metadata you provided when creating the invoice
`data.callBackUrl`	string	The URL receiving this webhook
`data.dateCreated`	string	ISO 8601 timestamp when the invoice was created

Expected Response

Your server should respond with a 2xx status code (preferably 200 OK) to acknowledge receipt of the webhook. The response body is not used by our system.

Status: 200 OK

Implementation Notes

Idempotency: The same webhook may be sent multiple times if we don't receive a timely response. Implement idempotency using the webhook id to prevent duplicate processing.

Retry Logic: We will retry failed webhook deliveries (non-2xx responses or timeouts) up to 3 times with exponential backoff.

Webhook Security: We recommend validating the webhook source by:

Using HTTPS for your endpoint

Implementing IP allowlisting (contact support for current IP ranges)

Verifying the webhook data against your database records

Timeout: Webhooks must be processed within 30 seconds, or the connection will be terminated. For long-running tasks, acknowledge the webhook quickly and process asynchronously.

🔐 Security Note: Always validate incoming webhooks to ensure they originate from Tranzakt before processing them.

Code Example

Node.js (Express) Implementation

Event Types

Event Type	Description
`payment.successful`	Sent when a payment is successfully completed

More event types will be added in future releases.

Troubleshooting

If you're not receiving webhooks as expected:

Check your callback URL: Ensure it's publicly accessible and correctly specified when creating invoices

Verify your endpoint: Test it with tools like Postman to confirm it can receive POST requests

Check response codes: Your endpoint must return a 2xx status code within 30 seconds

Review logs: Examine your logs for any errors in webhook processing

Contact support: If issues persist, contact Tranzakt support for assistance

⚠️ Remember that webhooks are only delivered if your endpoint is accessible from the internet. Local development servers may need to use a tunneling service like ngrok.

For more assistance, email support at hi@tranzakt.app

Overview#

Webhook Architecture#

POST Payment Webhook#

Endpoint Setup#

Request Details#

Headers#

Request Body#

Request Body Fields#

Expected Response#

Implementation Notes#

Code Example#

Node.js (Express) Implementation#

Event Types#

Troubleshooting#