Webhook Notification¶

Overview¶

Key Information

Request Method: All requests use POST method
Data Format: JSON format
Purpose: Asynchronous transaction status notification

📋 Brief Description¶

1. Notification Mechanism Overview¶

When transaction status (Disbursements/Deposits) is updated, the system automatically pushes results to your pre-configured callback URL via HTTP POST. Proper handling and response are essential for transaction status synchronization.

2. Merchant Response Requirements¶

Mandatory Response: Return plain text OK (case-sensitive) after successful processing
Response Format: Direct text response, no JSON wrapping required
Processing Time: Recommended to respond within 10 seconds

3. Retry Strategy for Failures¶

If OK response is not received, the system retries automatically: - Total Attempts: 8 times maximum within 24 hours - Retry Intervals: 2s → 5s → 10s → 30s → 1h → 3h → 3h → 3h - Final State: After all retries fail, notification stops

4. Status Confirmation Method¶

If notification fails after all retries: - Use Query API to retrieve final transaction status

5. IP Whitelist Configuration¶

If your server has IP restrictions: - Contact our operations team in advance - Provide your server's outbound IP addresses

🔧 Technical Specifications¶

Request Method¶

Method: POST
Content-Type: application/json

Request Parameters¶

Parameter	Required	Type	Description
`tradeNo`	Yes	String	Merchant transaction number.
`platFormTradeNo`	Yes	String	Unique Vexora transaction number.
`paymentTradeNo`	No	String	Unique Vexora transaction number for the current collection payment. Returned only for successful collection transactions. Repeated payments for the same order have different values.
`status`	Yes	String	Transaction status code used for merchant-side processing. • 0000: Successful. • 0001: Partially paid; use `amount` as the amount received in this payment. • 0015: Processing. • 00029: Failed. • Other codes: Treat as failed.
`message`	Yes	String	Transaction status description.
`amount`	Yes	String	Actual transaction amount. For partial collection payments, this is the amount received in the current payment.
`paymentInfo`	No	String	Payment information. Returned for both successful and failed collection transactions; not returned for disbursement transactions.
`serviceAmount`	No	String	Service fee. Returned for successful collection and disbursement transactions.
`claveRastreo`	No	String	Tracking number. Returned for successful collection transactions; not returned for disbursement transactions.
`payerAccount`	No	String	Payer account information. Returned for successful collection transactions.
`successTime`	Yes	String	Transaction completion time in local time (`YYYY-MM-DD HH:mm:ss`).
`timestamp`	Yes	String	Notification timestamp in milliseconds, represented as a string.
`sign`	Yes	String	Signature used to verify the notification payload.

📝 Examples¶

Request Example¶

{
    "tradeNo": "00000020",
    "platFormTradeNo": "5286e98841194687a95d25b5f3be346d",
    "paymentTradeNo": "9384kfsmco83sjdf",
    "status": "0000",
    "message": "SUCCESS",
    "amount": "30000",
    "paymentInfo": "6841800930023213210",
    "serviceAmount": "10",
    "claveRastreo": "20240701183431000001",
    "payerAccount": "123456789012345678",
    "successTime": "2024-07-01 18:34:31",
    "timestamp": "1724740395968",
    "sign": "d41d8cd98f00b204e9800998ecf8427e"
}

Response Example¶

OK

Response for a Failure Notification¶

OK

Note: Even for error notifications, respond with "OK" after processing