API reference
中文Payments
Create direct and hosted-checkout payments, and query them. Includes the amount tiers that wallets and some card channels round to.
Create Payment Order (Unified Entry)
POST/api/v1/payments/createNotes:
/api/v1/payments/createis the unified payment entry point- HansaPay routes the request according to
payment_method - Supported
payment_methodvalues:CARDCASH_APPPAYPAL(not currently available)APPLE_PAYGOOGLE_PAYPIX(not currently available)
Common fields:
| Field | Type | Required | Description |
|---|---|---|---|
payment_method | string | Yes | Payment method |
merchant_order_no | string | Yes | Merchant order number, max 64 characters, unique across your orders and refunds |
trans_amount.currency | string | Yes | 3-letter uppercase currency, for example USD. One of the supported currencies (see Important Notes) |
trans_amount.value | string | Yes | Amount string, for example 99.99: at most 2 decimals, none in JPY, up to 3 in OMR |
notify_url | string | Yes | Asynchronous result notification URL |
return_url | string | No | Frontend return URL after payment |
trade_info.goods_name | string | Yes | Product name |
trade_info.description | string | No | Product description |
metadata | string | No | Merchant passthrough field, returned unchanged in notifications |
client_ip | string | No | Client IP recorded by the merchant |
Direct Card Payment
Applicable when:
payment_method=CARD
Additional fields:
| Field | Type | Required | Description |
|---|---|---|---|
payer.email | string | No | Payer email |
payer.mobile | string | No | Payer mobile |
payer.user_name | string | No | User name |
payer.user_agent | string | No | Browser UA |
payer.ext_type | string | No | Channel-specific extra field |
payer.payer_id | string | No | Wallet-side payer identifier |
card.card_number | string | Yes | Card number |
card.cardholder_name | string | Yes | Cardholder name |
card.exp_month | int | Yes | Expiration month, 1-12 |
card.exp_year | int | Yes | Expiration year, 4 digits |
card.cvc | string | Yes | CVV/CVC |
billing_address.country | string | Yes | 2-letter country code, for example US |
billing_address.first_name | string | No | First name |
billing_address.last_name | string | No | Last name |
billing_address.email | string | No | |
billing_address.phone | string | No | Phone |
billing_address.state | string | No | State / province |
billing_address.city | string | No | City |
billing_address.address | string | No | Address |
billing_address.street_number | string | No | Street number |
billing_address.postal_code | string | No | Postal code |
billing_address.document | string | No | Local document ID if required |
shipping_address.* | object | No | If provided, full shipping address validation applies |
device_ip | string | Yes | Public device IP |
browser.accept | string | No | Browser Accept header |
browser.user_agent | string | No | Browser UA |
browser.accept_language | string | No | Language |
browser.java_enabled | bool | No | Whether Java is enabled |
browser.color_depth | string | No | Color depth |
browser.screen_height | string | No | Screen height |
browser.screen_width | string | No | Screen width |
browser.time_zone_offset | string | No | Timezone offset |
browser.referer | string | No | Referer |
For the best approval rate, send every field you have, even the optional ones. Card networks and issuers use the full billing address, email, phone, shipping address, the payer's real device_ip and the browser fields in their risk checks, and some acquirers require them. Missing details can lead to more declines. For US and Canadian addresses, send state as the two-letter code (CA, ON) and postal_code as 12345 or 12345-6789 (US) or A1B 2C3 (Canada).
Card payment request example:
{
"payment_method": "CARD",
"merchant_order_no": "M202406240001",
"trans_amount": {
"currency": "USD",
"value": "99.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",
"card": {
"card_number": "4111111111111111",
"cardholder_name": "JOHN DOE",
"exp_month": 12,
"exp_year": 2028,
"cvc": "123"
},
"billing_address": {
"country": "US",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "15551234567",
"state": "CA",
"city": "San Francisco",
"address": "Market Street",
"street_number": "1355",
"postal_code": "94103"
},
"device_ip": "203.0.113.10",
"client_ip": "203.0.113.10"
}Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | CARD |
order_no | string | HansaPay order number |
merchant_order_no | string | Merchant order number |
status | string | Order status |
trans_amount | object | Amount charged |
next_action | string | SUCCESS / 3DS_VERIFICATION_REQUIRED / PROCESSING / FAILED |
masked_card_number | string | Masked card number |
three_ds_url | string | Present when next_action=3DS_VERIFICATION_REQUIRED; redirect the payer to it |
created_at | string | Creation time |
Notes:
- This response has no
requested_amount, even when the amount was rounded to a price point; use the query or the notification - If the card is declined, the response is
code=422,Payment request failed|paymentFailed, withoutorder_no; apayment.updatednotification withstatus=FAILEDfollows - Invalid card number, CVC or expiry is reported as
System busy, please try again later|systemBusy
Direct Wallet Payment
Applicable when:
payment_method=CASH_APPpayment_method=APPLE_PAYpayment_method=GOOGLE_PAYpayment_method=PAYPALandpayment_method=PIXare not currently available (code=3003)
APPLE_PAY and GOOGLE_PAY are hosted wallet pages: redirect the payer to pay_url, where the wallet sheet is presented and the payment is completed. HansaPay never collects card data for these methods. Payer fields are optional unless the routed channel requires them (the error message names any missing field). After paying, the payer returns to HansaPay's result page, which shows the outcome and then sends them to your return_url.
CASH_APP: redirect the payer to pay_url. Depending on the channel the order is routed to, it is either a HansaPay payment page or the processor's Cash App Pay page:
- The HansaPay page shows the payment as an "Open Cash App" button on a phone and a QR code to scan on a computer, follows it until it is paid, then sends the payer to your
return_url. Its payment request is only payable for a limited time (currently 15 minutes); after that the payer starts a new payment from your site. - On the processor's Cash App Pay page the payer approves the payment in Cash App, then returns to HansaPay's result page and from there to your
return_url. On these channels Cash App uses the wallet price points below.
Wallet price points. The wallet provider only charges a fixed set of price points (USD 4.99, 5.99, 6.99, 7.99, 8.99, 9.90, 9.99, 10.99, 11.99, 12.99, 13.99, 14.99, 15.99, 17.99, 19.80, 19.99, 24.99, 29.99, 30.99, 39.99, 49.50, 49.99, 59.99, 89.99, 99.99, 124.99, 129.99, 149.99, 159.99, 199.99, 249.99, 299.99, 399.99, 499.99). When an APPLE_PAY or GOOGLE_PAY order is created (or a CASH_APP order on a channel that uses the processor's Cash App Pay page) (or a card checkout is switched to a wallet with the express buttons), HansaPay rounds the amount down to the nearest price point: a request for USD 11.00 is charged, settled and reported as USD 10.99. trans_amount in every response, query result and notification is the charged amount; the original request is returned alongside as requested_amount (same shape as trans_amount, omitted when nothing was rounded). Fees are calculated on the charged amount. Amounts below USD 4.99, above USD 499.99, or more than 5% above the nearest lower price point are not accepted for wallets: POST/api/v1/payments/create returns code=422 (notSupported) and the checkout page simply does not show the wallet buttons, so the payer pays by card. Reconcile wallet orders on order_no / merchant_order_no, never on an exact amount match.
Card price points on some channels. Some card channels accept only a fixed set of price points (USD 9.99, 10.99, 11.99, 12.99, 13.99, 14.99, 17.99, 19.99, 24.99, 29.99, 30.99, 39.99, 49.99, 59.99, 99.99, 124.99, 129.99, 149.99, 199.99, 249.99, 299.99, 399.99, 499.99). When a CARD order, direct or hosted checkout, is routed to such a channel, HansaPay rounds the amount down to the nearest point when the order is created, within the same 5%: a request for USD 12.50 is charged, settled and reported as USD 11.99, with requested_amount carrying USD 12.50. An amount no point fits (below USD 9.99, above USD 499.99, or more than 5% above the nearest lower point) is routed to another card channel; only when no channel can take it does POST/api/v1/payments/create return an amount error (code=2006). Every card price point is also a wallet price point, so a checkout switched to a wallet with the express buttons is not rounded a second time. As for wallets, reconcile on order_no / merchant_order_no, never on an exact amount match.
Additional fields:
| Field | Type | Required | Description |
|---|---|---|---|
payer.email | string | No | Payer email |
payer.mobile | string | No | Payer mobile |
payer.user_name | string | No | User name |
payer.user_agent | string | No | Browser UA |
payer.ext_type | string | No | Channel-specific extra field |
payer.payer_id | string | No | Wallet-side payer identifier |
payer.document | string | No | Payer tax/ID number |
Some channels require extra payer fields. Missing or malformed values are rejected before the order is
created, and the error message names the missing field, for example payer.document.
Wallet payment request example:
{
"payment_method": "CASH_APP",
"merchant_order_no": "M202406240003",
"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": "Gift Card",
"description": "Cash App checkout"
},
"metadata": "channel=cashapp",
"payer": {
"email": "[email protected]",
"payer_id": "PAYER123456"
},
"client_ip": "1.1.1.1"
}Notes:
- After wallet payment creation succeeds, the merchant frontend should directly redirect the user using
pay_url - When
next_action=REDIRECT, redirect immediately topay_url - Wallet payments do not need the checkout flow
- If
code=2006is returned, the collection amount does not satisfy the current available channel limits
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
order_no | string | HansaPay order number |
merchant_order_no | string | Merchant order number |
status | string | Order status |
trans_amount | object | Amount and currency |
requested_amount | object | The amount you sent, present only when it was rounded to a price point |
next_action | string | REDIRECT / QRCODE / SUCCESS / FAILED |
pay_url | string | Wallet redirect URL. Present when next_action=REDIRECT |
qr_code | string | Raw QR payment payload. Present when next_action=QRCODE; no available payment method uses it today |
created_at | string | RFC3339 creation time |
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CASH_APP",
"order_no": "O202406240003",
"merchant_order_no": "M202406240003",
"status": "PENDING",
"trans_amount": {
"currency": "USD",
"value": "49.99"
},
"next_action": "REDIRECT",
"pay_url": "https://wallet.example.com/redirect/pay_abc123",
"created_at": "2026-06-24T10:03:00+08:00"
}
}Checkout Payment
POST/api/v1/payments/checkoutNotes:
- Checkout mode creates a
payment_method=CARDorder and returns a hosted checkout page - Checkout mode also accepts the wallet methods (
APPLE_PAY,GOOGLE_PAY,CASH_APP);checkout_urlis then the wallet payment page - Save
checkout_urlas soon as you receive it. It expires after 30 minutes, the query does not return it, and repeating the request with the samemerchant_order_nois rejected as a duplicate. An order whose link expired unpaid staysCHECKOUT_REQUIRED - If the merchant also has Apple Pay and/or Google Pay channels enabled, the checkout page shows express wallet buttons above the card form. When the payer chooses a wallet, the same order (same
order_noandmerchant_order_no) is switched topayment_method=APPLE_PAYorGOOGLE_PAYand the payer is redirected to the wallet page; later query results and notifications report the wallet method and its fee snapshot. If the amount is not a wallet price point it is rounded down at the moment of the switch (see Wallet price points above); for USD orders the page tells the payer the exact wallet charge before they tap, andrequested_amountcarries the original amount afterwards. - Payer chooses the wallet (turned on by HansaPay for your account on request): a checkout for
APPLE_PAY,GOOGLE_PAYorCASH_APPopens a page listing every wallet your account can take at that amount, and the payer picks one. Nothing is charged until they do. The order keeps itsorder_noandmerchant_order_no; query results and notifications report the wallet the payer chose aspayment_method, which can differ from the one you sent. When only one wallet is available the checkout behaves as without the setting. - For server-to-server wallet payments without the hosted page, use POST/api/v1/payments/create
- If
code=2006is returned, the collection amount does not satisfy the current available channel limits
Differences from direct payment
- No
card - No
billing_address - No
device_ip - The user enters payment details on the checkout page
Core request fields
| Field | Required | Description |
|---|---|---|
payment_method | Yes | CARD, or a wallet method |
merchant_order_no | Yes | Merchant order number |
trans_amount | Yes | Amount and currency |
notify_url | Yes | Asynchronous notification URL |
return_url | No | Return URL after payment |
trade_info | Yes | Product information |
metadata | No | Merchant passthrough field |
payer | No | Payer information |
client_ip | No | Client IP |
billing_address | No | CARD only. The payer's billing address, with the fields of the direct card payment (see Direct Card Payment); country is required when it is sent |
shipping_address | No | CARD only. The shipping address, with the fields of the direct card payment; every field except street_number and document is required when it is sent |
- On some card channels the payer enters the card on the card processor's own page. The processor approves more payments when it knows more about the payer, so send
payer,client_ip(the payer's own IP, not your server's),billing_addressandshipping_addresswhenever you have them. Our own checkout page asks the payer for the billing address itself.
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
order_no | string | HansaPay order number |
merchant_order_no | string | Merchant order number |
status | string | Order status |
trans_amount | object | Amount and currency |
requested_amount | object | The amount you sent, present only when it was rounded to a price point |
next_action | string | Next action |
token | string | Checkout token |
checkout_url | string | Checkout URL |
created_at | string | Creation time |
Notes:
- For
CARD,statusandnext_actionareCHECKOUT_REQUIRED. For wallet methods,statusisPENDINGandnext_actionisREDIRECT; when the payer chooses the wallet,statusisCHECKOUT_REQUIREDuntil they have chosen (next_actionis stillREDIRECT) - On some card channels the payer enters the card on the card processor's own secure page:
checkout_urlthen takes the payer straight there, andstatusisPENDING(next_actionis stillCHECKOUT_REQUIRED). Redirect tocheckout_urleither way; the payer returns to the checkout's result page and then to yourreturn_url - If the payer uses an express wallet button on the checkout page,
payment_methodin later query results and notifications will beAPPLE_PAYorGOOGLE_PAY.trans_amountmay then be lower than the amount you requested (wallet price points); the requested amount is returned asrequested_amount. The same applies to a card order routed to a channel with card price points (see Card price points on some channels).
Full success response example
{
"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"
}
}Query Payment Order
POST/api/v1/payments/queryRequest fields
Provide one of the following:
| Field | Type | Required | Description |
|---|---|---|---|
order_no | string | One of two | HansaPay order number |
merchant_order_no | string | One of two | Merchant order number |
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
order_no | string | HansaPay order number |
merchant_order_no | string | Merchant order number |
status | string | Order status |
trans_amount | object | 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 |
paid_at | string | Payment completion time |
created_at | string | Creation time |
masked_card_number | string | Masked card number, usually empty for wallet payments |
trade_info | object | Product information |
metadata | string | Merchant passthrough field |
Order status values: PENDING, CHECKOUT_REQUIRED, 3DS_VERIFICATION_REQUIRED, PROCESSING, SUCCESS, FAILED, PARTIAL_REFUNDED, REFUNDED.
Notes:
- A query on an order that is still in progress also fetches the latest status from the provider
- In rare cases a card payment reported as
FAILEDis later confirmed as paid and changes toSUCCESS, with a new notification
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CARD",
"order_no": "O202406240001",
"merchant_order_no": "M202406240001",
"status": "SUCCESS",
"trans_amount": {
"currency": "USD",
"value": "99.99"
},
"paid_at": "2026-06-24T10:01:23+08:00",
"created_at": "2026-06-24T10:00:00+08:00",
"masked_card_number": "411111******1111",
"trade_info": {
"goods_name": "VIP Membership",
"description": "Monthly subscription"
},
"metadata": "biz=member&uid=10001"
}
}