Products
Developers
Resources
Company

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-MerchantID
  • X-Timestamp
  • X-Nonce
  • X-Sign

The verification rule is identical to request signing:

Text
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBody

Recommended merchant-side processing:

  1. Read the raw HTTP body as-is
  2. Read X-MerchantID, X-Timestamp, X-Nonce, X-Sign
  3. Recalculate the signature using the merchant secret
  4. Compare the signatures
  5. Process business logic only after verification succeeds
  6. Return plain text success

Java Verification Example

Java
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
<?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

Go
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

FieldTypeDescription
eventstringpayment.updated / refund.updated / payout.updated
order_nostringHansaPay order number
merchant_order_nostringMerchant order number
payment_methodstringPayment method
trans_amountobjectPayments and refunds: the USD amount charged or refunded, which differs from the API response for orders in another currency. Payouts: the payout amount
requested_amountobjectThe 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_infoobjectPayments: product information. Refunds: goods_name holds the refund reason
statusstringCurrent status
status_reasonstringPayouts only, when failed or canceled: Payout request failed, Recipient not valid, Payout failed or Payout canceled
metadatastringMerchant passthrough field
original_order_nostringOriginal HansaPay order number, for refunds
original_merchant_order_nostringOriginal merchant order number, for refunds
finished_atstringCompletion time. Not sent for refunds or failed payments
created_atstringCreation time

A failed payment notification does not include the reason for the failure.

Payment Notification Example

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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:

Text
success

Requirements:

  • 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