# 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

| 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

```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`
