Products
Developers
Resources
Company

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/create

Notes:

  • /api/v1/payments/create is the unified payment entry point
  • HansaPay routes the request according to payment_method
  • Supported payment_method values:
    • CARD
    • CASH_APP
    • PAYPAL (not currently available)
    • APPLE_PAY
    • GOOGLE_PAY
    • PIX (not currently available)

Common fields:

FieldTypeRequiredDescription
payment_methodstringYesPayment method
merchant_order_nostringYesMerchant order number, max 64 characters, unique across your orders and refunds
trans_amount.currencystringYes3-letter uppercase currency, for example USD. One of the supported currencies (see Important Notes)
trans_amount.valuestringYesAmount string, for example 99.99: at most 2 decimals, none in JPY, up to 3 in OMR
notify_urlstringYesAsynchronous result notification URL
return_urlstringNoFrontend return URL after payment
trade_info.goods_namestringYesProduct name
trade_info.descriptionstringNoProduct description
metadatastringNoMerchant passthrough field, returned unchanged in notifications
client_ipstringNoClient IP recorded by the merchant

Direct Card Payment

Applicable when:

  • payment_method=CARD

Additional fields:

FieldTypeRequiredDescription
payer.emailstringNoPayer email
payer.mobilestringNoPayer mobile
payer.user_namestringNoUser name
payer.user_agentstringNoBrowser UA
payer.ext_typestringNoChannel-specific extra field
payer.payer_idstringNoWallet-side payer identifier
card.card_numberstringYesCard number
card.cardholder_namestringYesCardholder name
card.exp_monthintYesExpiration month, 1-12
card.exp_yearintYesExpiration year, 4 digits
card.cvcstringYesCVV/CVC
billing_address.countrystringYes2-letter country code, for example US
billing_address.first_namestringNoFirst name
billing_address.last_namestringNoLast name
billing_address.emailstringNoEmail
billing_address.phonestringNoPhone
billing_address.statestringNoState / province
billing_address.citystringNoCity
billing_address.addressstringNoAddress
billing_address.street_numberstringNoStreet number
billing_address.postal_codestringNoPostal code
billing_address.documentstringNoLocal document ID if required
shipping_address.*objectNoIf provided, full shipping address validation applies
device_ipstringYesPublic device IP
browser.acceptstringNoBrowser Accept header
browser.user_agentstringNoBrowser UA
browser.accept_languagestringNoLanguage
browser.java_enabledboolNoWhether Java is enabled
browser.color_depthstringNoColor depth
browser.screen_heightstringNoScreen height
browser.screen_widthstringNoScreen width
browser.time_zone_offsetstringNoTimezone offset
browser.refererstringNoReferer

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:

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

FieldTypeDescription
payment_methodstringCARD
order_nostringHansaPay order number
merchant_order_nostringMerchant order number
statusstringOrder status
trans_amountobjectAmount charged
next_actionstringSUCCESS / 3DS_VERIFICATION_REQUIRED / PROCESSING / FAILED
masked_card_numberstringMasked card number
three_ds_urlstringPresent when next_action=3DS_VERIFICATION_REQUIRED; redirect the payer to it
created_atstringCreation 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, without order_no; a payment.updated notification with status=FAILED follows
  • Invalid card number, CVC or expiry is reported as System busy, please try again later|systemBusy

Direct Wallet Payment

Applicable when:

  • payment_method=CASH_APP
  • payment_method=APPLE_PAY
  • payment_method=GOOGLE_PAY
  • payment_method=PAYPAL and payment_method=PIX are 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:

FieldTypeRequiredDescription
payer.emailstringNoPayer email
payer.mobilestringNoPayer mobile
payer.user_namestringNoUser name
payer.user_agentstringNoBrowser UA
payer.ext_typestringNoChannel-specific extra field
payer.payer_idstringNoWallet-side payer identifier
payer.documentstringNoPayer 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:

JSON
{
  "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 to pay_url
  • Wallet payments do not need the checkout flow
  • If code=2006 is returned, the collection amount does not satisfy the current available channel limits

Successful data

FieldTypeDescription
payment_methodstringPayment method
order_nostringHansaPay order number
merchant_order_nostringMerchant order number
statusstringOrder status
trans_amountobjectAmount and currency
requested_amountobjectThe amount you sent, present only when it was rounded to a price point
next_actionstringREDIRECT / QRCODE / SUCCESS / FAILED
pay_urlstringWallet redirect URL. Present when next_action=REDIRECT
qr_codestringRaw QR payment payload. Present when next_action=QRCODE; no available payment method uses it today
created_atstringRFC3339 creation time

Full success response example

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

Notes:

  • Checkout mode creates a payment_method=CARD order and returns a hosted checkout page
  • Checkout mode also accepts the wallet methods (APPLE_PAY, GOOGLE_PAY, CASH_APP); checkout_url is then the wallet payment page
  • Save checkout_url as soon as you receive it. It expires after 30 minutes, the query does not return it, and repeating the request with the same merchant_order_no is rejected as a duplicate. An order whose link expired unpaid stays CHECKOUT_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_no and merchant_order_no) is switched to payment_method=APPLE_PAY or GOOGLE_PAY and 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, and requested_amount carries the original amount afterwards.
  • Payer chooses the wallet (turned on by HansaPay for your account on request): a checkout for APPLE_PAY, GOOGLE_PAY or CASH_APP opens 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 its order_no and merchant_order_no; query results and notifications report the wallet the payer chose as payment_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=2006 is 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

FieldRequiredDescription
payment_methodYesCARD, or a wallet method
merchant_order_noYesMerchant order number
trans_amountYesAmount and currency
notify_urlYesAsynchronous notification URL
return_urlNoReturn URL after payment
trade_infoYesProduct information
metadataNoMerchant passthrough field
payerNoPayer information
client_ipNoClient IP
billing_addressNoCARD 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_addressNoCARD 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_address and shipping_address whenever you have them. Our own checkout page asks the payer for the billing address itself.

Successful data

FieldTypeDescription
payment_methodstringPayment method
order_nostringHansaPay order number
merchant_order_nostringMerchant order number
statusstringOrder status
trans_amountobjectAmount and currency
requested_amountobjectThe amount you sent, present only when it was rounded to a price point
next_actionstringNext action
tokenstringCheckout token
checkout_urlstringCheckout URL
created_atstringCreation time

Notes:

  • For CARD, status and next_action are CHECKOUT_REQUIRED. For wallet methods, status is PENDING and next_action is REDIRECT; when the payer chooses the wallet, status is CHECKOUT_REQUIRED until they have chosen (next_action is still REDIRECT)
  • On some card channels the payer enters the card on the card processor's own secure page: checkout_url then takes the payer straight there, and status is PENDING (next_action is still CHECKOUT_REQUIRED). Redirect to checkout_url either way; the payer returns to the checkout's result page and then to your return_url
  • If the payer uses an express wallet button on the checkout page, payment_method in later query results and notifications will be APPLE_PAY or GOOGLE_PAY. trans_amount may then be lower than the amount you requested (wallet price points); the requested amount is returned as requested_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

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

Request fields

Provide one of the following:

FieldTypeRequiredDescription
order_nostringOne of twoHansaPay order number
merchant_order_nostringOne of twoMerchant order number

Successful data

FieldTypeDescription
payment_methodstringPayment method
order_nostringHansaPay order number
merchant_order_nostringMerchant order number
statusstringOrder status
trans_amountobjectAmount
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
paid_atstringPayment completion time
created_atstringCreation time
masked_card_numberstringMasked card number, usually empty for wallet payments
trade_infoobjectProduct information
metadatastringMerchant 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 FAILED is later confirmed as paid and changes to SUCCESS, with a new notification

Full success response example

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