Getting started
中文Merchant API
Integrate HansaPay from your server: card and wallet payments, refunds and signed notifications. Every endpoint is a JSON POST signed with HMAC-SHA256.
- AuthenticationSign requests, verify responses
- Responses & errorsResponse structure, error codes
- PaymentsCreate, checkout, query
- RefundsCreate, query
- PayoutsCash App: create, query, precheck
- NotificationsSigned result notifications
Base URLs
Integrate against the test environment first, then switch the base URL and credentials for production. Every endpoint is a POST with a JSON body, and every request is signed. Examples in the reference use https://api.example.com as a placeholder host.
https://api-test.hansapay.iohttps://api.hansapay.ioQuick start
The quickest first payment is a hosted checkout. You send the order, HansaPay returns a checkout_url, and the payer enters their card details on HansaPay's page, so you never handle card data. Signing is explained under Authentication.
{
"payment_method": "CARD",
"merchant_order_no": "M202406240002",
"trans_amount": {
"currency": "USD",
"value": "49.99"
},
"notify_url": "https://merchant.example.com/callback/payment",
"return_url": "https://merchant.example.com/pay/success",
"trade_info": {
"goods_name": "VIP Membership",
"description": "Monthly subscription"
},
"metadata": "biz=member&uid=10001",
"client_ip": "203.0.113.10"
}BODY='{"payment_method":"CARD","merchant_order_no":"M202406240002","trans_amount":{"currency":"USD","value":"49.99"},"notify_url":"https://merchant.example.com/callback/payment","return_url":"https://merchant.example.com/pay/success","trade_info":{"goods_name":"VIP Membership","description":"Monthly subscription"},"metadata":"biz=member&uid=10001","client_ip":"203.0.113.10"}'
TIMESTAMP="$(date +%s)"
NONCE="$(openssl rand -hex 8)"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)
curl -X POST "https://api-test.hansapay.io/api/v1/payments/checkout" \
-H "Content-Type: application/json" \
-H "X-MerchantID: ${MERCHANT_ID}" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Nonce: ${NONCE}" \
-H "X-Sign: ${SIGN}" \
-d "$BODY"import crypto from "node:crypto";
const body = JSON.stringify({
payment_method: "CARD",
merchant_order_no: "M202406240002",
trans_amount: {
currency: "USD",
value: "49.99"
},
notify_url: "https://merchant.example.com/callback/payment",
return_url: "https://merchant.example.com/pay/success",
trade_info: {
goods_name: "VIP Membership",
description: "Monthly subscription"
},
metadata: "biz=member&uid=10001",
client_ip: "203.0.113.10"
});
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomBytes(8).toString("hex");
const sign = crypto
.createHmac("sha256", process.env.SECRET_KEY)
.update(`${process.env.MERCHANT_ID}\n${timestamp}\n${nonce}\n${body}`)
.digest("hex");
const res = await fetch("https://api-test.hansapay.io/api/v1/payments/checkout", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-MerchantID": process.env.MERCHANT_ID,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
"X-Sign": sign,
},
body, // send exactly the string you signed
});
const { code, msg, data } = JSON.parse(await res.text());<?php
$merchantId = getenv('MERCHANT_ID');
$secret = getenv('SECRET_KEY');
$rawBody = '{"payment_method":"CARD","merchant_order_no":"M202406240002","trans_amount":{"currency":"USD","value":"49.99"},"notify_url":"https://merchant.example.com/callback/payment","return_url":"https://merchant.example.com/pay/success","trade_info":{"goods_name":"VIP Membership","description":"Monthly subscription"},"metadata":"biz=member&uid=10001","client_ip":"203.0.113.10"}';
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(8));
$payload = $merchantId . "\n" . $timestamp . "\n" . $nonce . "\n" . $rawBody;
$sign = hash_hmac('sha256', $payload, $secret);
$ch = curl_init('https://api-test.hansapay.io/api/v1/payments/checkout');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $rawBody,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-MerchantID: ' . $merchantId,
'X-Timestamp: ' . $timestamp,
'X-Nonce: ' . $nonce,
'X-Sign: ' . $sign,
],
]);
$response = json_decode(curl_exec($ch), true);{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CARD",
"order_no": "O202406240002",
"merchant_order_no": "M202406240002",
"status": "CHECKOUT_REQUIRED",
"trans_amount": {
"currency": "USD",
"value": "49.99"
},
"next_action": "CHECKOUT_REQUIRED",
"token": "5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
"checkout_url": "https://cashier.example.com/pay/5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
"created_at": "2026-06-24T10:05:00+08:00"
}
}Redirect the payer to checkout_url and save it straight away: it expires after 30 minutes and can't be retrieved again. When the payment completes, HansaPay sends a signed payment.updated notification to your notify_url.
Endpoints
Every route takes a signed JSON POST. To try them from a terminal, use the cURL examples. The same routes are described as OpenAPI at /openapi.json, and every docs page is also available as Markdown: add .md to its URL.
Payment APIs
| Route | Description |
|---|---|
| POST/api/v1/payments/create | Direct payment creation |
| POST/api/v1/payments/checkout | Checkout payment creation |
| POST/api/v1/payments/query | Query payment order |
Refund APIs
| Route | Description |
|---|---|
| POST/api/v1/refunds/create | Create refund |
| POST/api/v1/refunds/query | Query refund |
Payout APIs
| Route | Description |
|---|---|
| POST/api/v1/payouts/create | Create payout |
| POST/api/v1/payouts/query | Query payout |
| POST/api/v1/payouts/cancel | Cancel payout |
| POST/api/v1/payouts/precheck | Payout balance precheck |
