Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zafapay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Webhooks allow you to receive real-time notifications for payment events such as completion, failure, and refunds. ZAFA PAY sends HTTP POST requests to your registered webhook endpoints when payment status changes.
Webhook endpoints can be managed from the Webhooks tab in the merchant dashboard (https://app.zafapay.com). Each endpoint has its own Webhook Secret for signature verification.

​
Webhook Endpoints

You can register multiple webhook endpoints to receive event notifications. Each endpoint has its own URL, secret, and optional event filter.
FeatureDescription
Multiple endpointsRegister up to 16 webhook endpoints per merchant
Event filteringChoose which event types each endpoint receives. If no filter is set, the endpoint receives all events
Per-endpoint secretsEach endpoint has its own Webhook Secret (whsec_xxx format) for signature verification
Enable/disableEndpoints can be individually activated or deactivated without deletion
Webhook endpoints can be created and managed from the Webhooks tab in the merchant dashboard.

​
Event Types

EventDescription
payment.succeededPayment completed successfully
payment.failedPayment failed
payment.canceledPayment canceled — either voided by the merchant (POST /v1/payments/{id}/void) or canceled by the customer during 3D Secure authentication on the hosted checkout page
payment.refundedRefund completed
payment.chargebackChargeback occurred

​
Payload

​
event
string
Event type (e.g., payment.succeeded)
​
transaction_id
string
Transaction ID
​
merchant_id
string
Merchant ID
​
merchant_name
string
Merchant name
​
status
string
Payment status (succeeded, failed, canceled, refunded, chargeback)
​
amount
string
Payment amount (string format, e.g., "100.00")
​
currency
string
Currency code
​
payment_method
string
Payment method (card, depot, etc.)
​
payment_method_id
string
Saved card ID (pmi_xxx format). Only included for recurring payments or when save_card was used
​
is_recurring
boolean
true for recurring (subscription) payments
​
save_card
boolean
Only included as true when the card was saved for future use
​
external_id
string
Merchant’s order ID (the value specified when creating the payment)
​
product_name
string
Product name (the value specified when creating the payment)
​
customer_id
string
Customer ID (the value specified when creating the payment)
​
email
string
Customer’s email address (the value specified when creating the payment)
​
tel
string
Customer’s phone number (the value specified when creating the payment)
​
amount_refunded
string
Refunded amount (string format. payment.refunded event only)
​
error
object
Error details (payment.failed event only)
​
card_brand
string
Card brand (visa, mastercard, amex, jcb, etc.)
​
card_last4
string
Last 4 digits of the card number
​
cardholder_name
string
Cardholder name
​
card_exp_month
number
Card expiration month
​
card_exp_year
number
Card expiration year
​
card_country
string
Card issuing country (ISO 3166-1 alpha-2 code, e.g., US, JP, SG). Only included when BIN lookup data is available.
​
card_funding
string
Card funding type (credit, debit, prepaid). Only included when BIN lookup data is available.
​
metadata
object
Metadata specified when creating the payment
​
created_at
string
Transaction creation timestamp (ISO 8601 format)
​
timestamp
string
Webhook sent timestamp (ISO 8601 format)

​
Payload Examples

​
payment.succeeded (Payment Successful)

{
  "event": "payment.succeeded",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "Sample Store",
  "status": "succeeded",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "payment_method_id": "pmi_abc123",
  "is_recurring": false,
  "save_card": true,
  "external_id": "order_12345",
  "product_name": "Premium Plan",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:31:00Z"
}
  • payment_method_id is only included when save_card was used or for recurring payments
  • save_card is only included as true when the card was saved in the initial payment
  • is_recurring is true for recurring payments

​
payment.failed (Payment Failed)

{
  "event": "payment.failed",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "Sample Store",
  "status": "failed",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "Premium Plan",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "error": {
    "code": "card_declined",
    "category": "soft_decline",
    "message": "Your card was declined.",
    "recommended_action": "use_different_card"
  },
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:31:00Z"
}
The error object is only included in payment.failed events. Use recommended_action to determine the appropriate response (retry, contact_customer, use_different_card, or none).

​
payment.canceled (Payment Canceled)

{
  "event": "payment.canceled",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "Sample Store",
  "status": "canceled",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "Premium Plan",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:32:00Z"
}
payment.canceled fires in two cases:
  1. Merchant void — POST /v1/payments/{id}/void was called to void an authorized/captured payment before settlement.
  2. Customer cancel during 3DS — the customer clicked “Cancel Payment” on the hosted 3DS challenge page. The checkout link becomes immediately reusable; the customer can retry with a different card using the same payment link.
Both cases send the same event shape. If you need to distinguish them, use GET /v1/payments/{id} and inspect the transaction’s prior state, or rely on your own state tracking.

​
payment.refunded (Refund Completed)

{
  "event": "payment.refunded",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "Sample Store",
  "status": "refunded",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "Premium Plan",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "amount_refunded": "50.00",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-20T14:00:00Z"
}
The amount_refunded field is only included in payment.refunded events. For partial refunds, it shows the refunded amount.

​
payment.chargeback (Chargeback Occurred)

{
  "event": "payment.chargeback",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "Sample Store",
  "status": "chargeback",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "Premium Plan",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-02-01T09:00:00Z"
}
When a chargeback occurs, the transaction amount may be debited from the merchant. Please respond promptly.

​
Signature Verification

Webhook requests include a signature header. Verify this signature using the endpoint’s Webhook Secret to confirm the request was sent by ZAFA PAY.

​
Signature Header

EnvironmentHeader Name
SandboxX-Zafapay-Signature-Sandbox
ProductionX-Zafapay-Signature

​
Verification Method

The signature is an HMAC-SHA256 hash of the request body (JSON string), using the endpoint’s Webhook Secret as the key.
Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === expectedSignature;
}

// Express.js example
app.post('/webhooks/zafapay', express.json(), (req, res) => {
  const signature = req.headers['x-zafapay-signature-sandbox'];
  // Use the Webhook Secret for this endpoint (whsec_xxx format)
  const secret = process.env.ZAFAPAY_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process event
  const { event, transaction_id, status } = req.body;

  switch (event) {
    case 'payment.succeeded':
      // Handle successful payment
      break;
    case 'payment.failed':
      // Handle failed payment
      break;
    case 'payment.refunded':
      // Handle refund
      break;
  }

  res.json({ received: true });
});

​
Response

Return HTTP status code 2xx when the webhook is successfully received. 
{
  "received": true
}

​
Retry

ZAFA PAY automatically retries webhooks in the following cases:
  • HTTP status code other than 2xx is returned
  • Connection timeout occurs (10 seconds)

​
Retry Schedule

AttemptDelay After Failure
1stImmediate
2nd1 minute later
3rd5 minutes later
4th30 minutes later
5th2 hours later
6th6 hours later
A total of 6 retries are executed over approximately 9 hours. If all retries fail, the event is moved to a Dead Letter Queue (DLQ) for manual intervention.
To prevent duplicate notifications from retries, ensure idempotency using transaction_id as the key.

​
Best Practices

1

Always Verify Signature

Signature verification is essential to prevent unauthorized requests
2

Ensure Idempotency

The same event may be sent multiple times. Use transaction_id as a key to prevent duplicate processing
3

Return Response Quickly

Process webhooks asynchronously and return 200 immediately. Long processing times will cause timeout retries
4

Log Errors

Log received payloads and processing results for debugging