API reference
中文Notifications
Signed notifications HansaPay sends to your notify_url when a payment, refund or payout changes status.
HansaPay will POST payment, refund, and payout result notifications to the notify_url provided in the original request.
No notification is sent for a chargeback, for a checkout link that expires unpaid, or when a payment changes to REFUNDED (a refund.updated is sent for the refund instead).
Notification Headers
Notification requests include:
X-MerchantIDX-TimestampX-NonceX-Sign
The verification rule is identical to request signing:
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBodyRecommended merchant-side processing:
- Read the raw HTTP body as-is
- Read
X-MerchantID,X-Timestamp,X-Nonce,X-Sign - Recalculate the signature using the merchant secret
- Compare the signatures
- Process business logic only after verification succeeds
- Return plain text
success
Java Verification Example
String merchantId = request.getHeader("X-MerchantID");
String timestamp = request.getHeader("X-Timestamp");
String nonce = request.getHeader("X-Nonce");
String receivedSign = request.getHeader("X-Sign");
String rawBody = requestBodyAsString;
String secret = "your_merchant_secret";
String payload = merchantId + "\n" + timestamp + "\n" + nonce + "\n" + rawBody;
String expectedSign = hmacSha256Hex(payload, secret);
if (!expectedSign.equalsIgnoreCase(receivedSign)) {
throw new RuntimeException("invalid signature");
}PHP Verification Example
<?php
$merchantId = $_SERVER['HTTP_X_MERCHANTID'];
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$nonce = $_SERVER['HTTP_X_NONCE'];
$receivedSign = $_SERVER['HTTP_X_SIGN'];
$rawBody = file_get_contents('php://input');
$secret = 'your_merchant_secret';
$payload = $merchantId . "\n" . $timestamp . "\n" . $nonce . "\n" . $rawBody;
$expectedSign = hash_hmac('sha256', $payload, $secret);
if (strtolower($expectedSign) !== strtolower($receivedSign)) {
throw new Exception('invalid signature');
}Go Verification Example
payload := merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(payload))
expected := hex.EncodeToString(mac.Sum(nil))
if !strings.EqualFold(expected, receivedSign) {
return errors.New("invalid signature")
}Notification Body Structure
HansaPay uses a unified notification body format for payment, refund, and payout events.
Notification Fields
| Field | Type | Description |
|---|---|---|
event | string | payment.updated / refund.updated / payout.updated |
order_no | string | HansaPay order number |
merchant_order_no | string | Merchant order number |
payment_method | string | Payment method |
trans_amount | object | Payments and refunds: the USD amount charged or refunded, which differs from the API response for orders in another currency. Payouts: the payout amount |
requested_amount | object | The amount the merchant originally requested; present only when the amount was rounded down to a supported upstream price point (wallets, and card on some channels), in which case trans_amount is the amount actually charged |
trade_info | object | Payments: product information. Refunds: goods_name holds the refund reason |
status | string | Current status |
status_reason | string | Payouts only, when failed or canceled: Payout request failed, Recipient not valid, Payout failed or Payout canceled |
metadata | string | Merchant passthrough field |
original_order_no | string | Original HansaPay order number, for refunds |
original_merchant_order_no | string | Original merchant order number, for refunds |
finished_at | string | Completion time. Not sent for refunds or failed payments |
created_at | string | Creation time |
A failed payment notification does not include the reason for the failure.
Payment Notification Example
{
"event": "payment.updated",
"order_no": "O202406240001",
"merchant_order_no": "M202406240001",
"payment_method": "CARD",
"trans_amount": {
"currency": "USD",
"value": "99.99"
},
"trade_info": {
"goods_name": "VIP Membership",
"description": "Monthly subscription"
},
"status": "SUCCESS",
"metadata": "biz=member&uid=10001",
"finished_at": "2026-06-24T10:01:23+08:00",
"created_at": "2026-06-24T10:00:00+08:00"
}Refund Notification Example
{
"event": "refund.updated",
"order_no": "R202406240001",
"merchant_order_no": "MR202406240001",
"payment_method": "CARD",
"trans_amount": {
"currency": "USD",
"value": "99.99"
},
"trade_info": {
"goods_name": "customer requested"
},
"status": "SUCCESS",
"metadata": "refund=manual",
"original_order_no": "O202406240001",
"original_merchant_order_no": "M202406240001",
"created_at": "2026-06-24T11:00:00+08:00"
}Payout Notification Example
{
"event": "payout.updated",
"order_no": "P202406240001",
"merchant_order_no": "MP202406240001",
"payment_method": "CASH_APP",
"trans_amount": {
"currency": "USD",
"value": "88.50"
},
"status": "SUCCESS",
"metadata": "batch=20260624",
"finished_at": "2026-06-24T12:00:08+08:00",
"created_at": "2026-06-24T12:00:00+08:00"
}Merchant Notification Response Requirement
After the merchant processes a notification successfully, it must return:
successRequirements:
- Plain text only
- No JSON wrapper
- No quotes
- Use lowercase
success - Reply within 5 seconds; do slow work afterwards
- HansaPay checks only the body; any other body counts as a failure, even with HTTP
200 - A notification that is not acknowledged is sent again, up to 9 attempts in total over about 90 minutes. Every attempt is signed again with a new timestamp and nonce
- The same notification can arrive more than once, and notifications can arrive out of order. The body shows the status at the time of sending. Notifications carry no event ID: deduplicate on
event+order_no+status
