Payment Status Change Webhook

Overview

The PAYMENT_STATUS_CHANGE webhook is triggered in real-time whenever an incoming deposit, wallet-to-wallet transfer, or external withdrawal transitions between states (such as Requested, Processing, Completed, or Failed).

Webhook Delivery

• HTTP Method: POST
• Destination: Your configured server webhook endpoint
• Content-Type: application/json

Webhook Headers

Header	Value	Description
Content-Type	application/json	Request body media type
x-webhook-event	PAYMENT_STATUS_CHANGE	Identifier of the dispatched event type
x-webhook-timestamp	ISO 8601 string	Timestamp when the event was dispatched

Event Payload

{
  "paymentId": "pm_456789",
  "oldStatus": "Requested",
  "newStatus": "Completed",
  "updatedAt": "2025-03-21T10:15:30Z"
}

Payload Fields

Field	Type	Required	Description
paymentId	string	Yes	Unique identifier of the payment transaction whose status updated.
oldStatus	string	Yes	The preceding status of the payment (e.g. Requested, Processing).
newStatus	string	Yes	The updated status of the payment (e.g. Completed, Failed).
updatedAt	string (ISO Date)	Yes	UTC timestamp when the state transition occurred.

Expected Server Response

Your webhook receiver endpoint must respond with an HTTP 200 OK status code to confirm successful receipt:

{
  "received": true
}

If your endpoint responds with a 4xx or 5xx error, or fails to respond within 5 seconds, our webhook delivery system will retry with exponential backoff.

Implementation Examples

Node.js (Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const eventType = req.headers['x-webhook-event'];
  const { paymentId, oldStatus, newStatus, updatedAt } = req.body;

  if (eventType === 'PAYMENT_STATUS_CHANGE') {
    console.log(`Payment ${paymentId} changed from ${oldStatus} to ${newStatus} at ${updatedAt}`);
    // Perform application state updates (e.g. update order balance)
  }

  // Acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook receiver running on port 3000'));

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event_type = request.headers.get('x-webhook-event')
    data = request.json or {}

    if event_type == 'PAYMENT_STATUS_CHANGE':
        payment_id = data.get('paymentId')
        old_status = data.get('oldStatus')
        new_status = data.get('newStatus')
        updated_at = data.get('updatedAt')
        print(f"Payment {payment_id} changed from {old_status} to {new_status} at {updated_at}")
        # Perform application state updates

    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Interactive Webhook Schema Explorer