Products
Developers
Resources
Company

Getting started

中文

What to expect

Where HansaPay behaves in ways an existing integration can't see for itself. Read this before you integrate.

The request and response formats in this document are unchanged, so an existing integration keeps working without code changes. The behaviour below is what an existing integration will not notice on its own:

  • Amounts can be rounded down to a price point. Apple Pay, Google Pay and some card channels only charge fixed price points. HansaPay rounds the amount down to the nearest point (at most 5%): trans_amount is the amount charged and requested_amount the amount you sent. See Direct Wallet Payment. Reconcile on order_no / merchant_order_no, never on the amount.
  • Notifications report the USD amount charged. For an order in another currency, API responses return the currency and amount you sent, while payment.updated and refund.updated notifications return the USD amount charged or refunded.
  • Payments in another currency carry an FX markup. A card or wallet payment in a currency other than USD is charged in USD at the market rate plus an FX markup (1.5% unless agreed otherwise). Your balance and your fees are worked out on your price at the market rate. The markup is not yours, so the USD amount in payment.updated is higher than what your balance is credited before fees. A refund or chargeback debits only your part.
  • Supported currencies. Payments and payment links can be priced in USD, EUR, GBP, CAD, AUD, NZD, CHF, JPY, HKD, SGD, PLN, SEK, NOK, AED, SAR, OMR. Any other currency is refused with code=422, and the message lists the supported ones. A price in a currency other than USD is converted at the day's market rate and charged in USD. If no current rate is available, the payment is refused with code=422 and the message "exchange rate is temporarily unavailable": retry later or charge in USD.
  • Chargebacks are not notified. A chargeback is held from your balance as soon as it is recorded: your part of the amount and the chargeback fee can no longer be withdrawn. It is debited from that hold on its settlement date. If your balance does not cover it, it goes below zero and your next income pays it first. Chargebacks are shown in the merchant portal only. No notification is sent and the payment status stays SUCCESS.
  • Card refunds are full refunds and are reviewed. Card, Apple Pay and Google Pay payments can be refunded once, for the full amount. The refund starts as PENDING and is reviewed before it completes. See Create Refund.
  • Suspended accounts cannot take payments. /payments/create and /payments/checkout return code=1001. Queries, refunds and settlement keep working.
  • Payment creation is rate-limited. Each merchant account can create up to 600 payments a minute through /payments/create and /payments/checkout together, unless agreed otherwise. Past that, the request is refused with HTTP 429 and code=4001 (tooManyRequests), and no order is created: wait a moment and retry with the same merchant_order_no. Queries, refunds and payouts are not counted.
  • PAYPAL and PIX are not currently available. They are accepted by validation and then rejected with code=3003. Payouts are available for CASH_APP only: to a Cash App $cashtag, in USD, once payouts are enabled for your account. Other payout methods return code=5007. See 8.
  • Notifications must be answered with success. Anything else is retried, up to 9 attempts over about 90 minutes. The same notification can arrive more than once. See Merchant Notification Response Requirement.
  • Settlement counts US business days. T+N counts Monday to Friday, excluding New Year's Day, Memorial Day, Independence Day, Labor Day, Thanksgiving Day and Christmas Day, from the day the order was created. Some payment channels only release funds on certain weekdays: a payment through one of them settles on the first such day on or after its T+N date (for example the following Friday). Each order's settle date is shown with the order.