Zenpay API Documentation

Overview

The Payout Manual Callback system allows CRM administrators and merchants to manually trigger callback notifications for payout transactions. This is essential for notifying merchants when payouts have been processed manually by administrators.

This endpoint enables merchants to receive real-time notifications about payout completions, allowing them to update their systems accordingly and provide immediate feedback to their customers.

This endpoint requires HMAC-SHA256 Signature Authentication with timestamp validation for enhanced security.

Authentication

The payout manual callback endpoint uses HMAC-SHA256 signature authentication for maximum security, consistent with all other ZenPay API endpoints.

Security Features

Request parameters are cryptographically signed using HMAC-SHA256
Signature includes timestamp for replay attack protection
Uses merchant-specific secret keys from the database
Cross-merchant access is prevented through signature validation
Only active merchants (status_id = 2) are allowed

Signature Generation

Sort parameters alphabetically: biller_code, ref_doc, timestamp
URL encode values using RFC 1738 encoding
Build query string (after URL encoding): biller_code=202500039&ref_doc=INV-2024-9990222×tamp=2025-01-15T10%3A30%3A00Z
Generate HMAC-SHA256 using your merchant secret key
Hex encode the result for the X-Signature header

Timestamp Validation: Must be within 5 minutes past to 1 minute future

Refer to the Signature Generation section for detailed steps.

Request

Http Method & URL

POST /v1/payouts/{ref_doc}/callbacks

Manually trigger a callback notification for a specific payout transaction using the payout reference document.

URL Parameters

Parameter	Type	Required	Description
ref_doc	string	Yes	Payout reference document (e.g., "INV-2024-9990222")

Headers

Header	Type	Required	Description
X-Signature	string	Yes	HMAC-SHA256 signature for request authentication
Content-Type	string	Yes	Must be "application/json"

Request Body Parameters

Parameter	Type	Required	Description
biller_code	string	Yes	Merchant identifier code
timestamp	string	Yes	Request timestamp in ISO 8601 format (UTC)

Request Body Example

{
  "biller_code": "202500039",
  "timestamp": "2025-01-15T10:30:00Z"
}

cURL Example

curl --location 'http://localhost:8080/v1/payouts/INV-2024-9990222/callbacks' \
--header 'X-Signature: a1b2c3d4e5f6789abcdef1234567890abcdef1234567890abcdef1234567890' \
--header 'Content-Type: application/json' \
--data '{
  "biller_code": "202500039",
  "timestamp": "2025-01-15T10:30:00Z"
}'

Response

Two-Level Status System

Outer Level: Indicates whether ZenPay successfully sent the callback

Inner Level: Indicates whether the merchant accepted the callback

Success Response (200)

{
  "success": true,
  "message": "Manual payout callback triggered successfully",
  "data": {
    "status": "SUCCESS",
    "message": "Callback sent successfully",
    "ref_doc": "INV-2024-9990222",
    "merchant_response": {
      "http_status": 200,
      "body": "{\"status\":\"received\"}",
      "error_code": "",
      "error_message": ""
    }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Failed Callback Response (200 - Merchant Rejected)

{
  "success": true,
  "message": "Manual payout callback triggered successfully",
  "data": {
    "status": "FAILED",
    "message": "Callback failed with HTTP status 404",
    "ref_doc": "INV-2024-9990222",
    "merchant_response": {
      "http_status": 404,
      "body": "404 page not found",
      "error_code": "HTTP_404",
      "error_message": "HTTP 404: 404 Not Found"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Missing Signature Error Response (401)

{
  "success": false,
  "message": "Authentication failed",
  "errors": [
    {
      "field": "X-Signature",
      "message": "Signature header is required"
    }
  ]
}

Invalid Signature Error Response (401)

{
  "success": false,
  "message": "Authentication failed",
  "errors": [
    {
      "field": "signature",
      "message": "Invalid signature"
    }
  ]
}

Invalid Timestamp Error Response (400)

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "timestamp",
      "message": "Timestamp must be within valid time window (5 minutes past to 1 minute future)"
    }
  ]
}

Payout Not Found Response (404)

{
  "success": false,
  "message": "Payout not found",
  "errors": [
    {
      "field": "ref_doc",
      "message": "Payout not found"
    }
  ]
}

No Callback URL Response (400)

{
  "success": false,
  "message": "No callback URL configured",
  "errors": [
    {
      "field": "callback_url",
      "message": "No callback URL configured for this payout"
    }
  ]
}

Callback Information

When the manual callback is triggered successfully, ZenPay sends a structured payload to the merchant's callback URL containing payout completion details.

Payload Details: For complete information about callback payload structure, field descriptions, and signature verification, see the Callback Parameters (Payout) page.

Quick Overview

The callback payload includes:

Transaction details: biller_code, ref_doc, amount, status
Bank information: bank_code, bank_account, bank_acc_holder
Processing data: member_id, processed_at, settlement_date
Security: HMAC-SHA256 signature in X-Signature header

Error Handling

Error Code Reference

HTTP Status	Error Type	Description	Action Required
400	Validation Error	Missing or invalid request parameters	Fix request format
401	Authentication Error	Invalid or missing signature	Check signature generation
404	Not Found	Payout reference doesn't exist	Verify ref_doc
500	Server Error	Internal server error	Contact support