Products
Developers
Resources
Company

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.

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.

Testhttps://api-test.hansapay.io
Productionhttps://api.hansapay.io

Quick 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"
}
200 · Response
{
  "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

RouteDescription
POST/api/v1/payments/createDirect payment creation
POST/api/v1/payments/checkoutCheckout payment creation
POST/api/v1/payments/queryQuery payment order

Refund APIs

RouteDescription
POST/api/v1/refunds/createCreate refund
POST/api/v1/refunds/queryQuery refund

Payout APIs

RouteDescription
POST/api/v1/payouts/createCreate payout
POST/api/v1/payouts/queryQuery payout
POST/api/v1/payouts/cancelCancel payout
POST/api/v1/payouts/precheckPayout balance precheck