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_amountis the amount charged andrequested_amountthe amount you sent. See Direct Wallet Payment. Reconcile onorder_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.updatedandrefund.updatednotifications 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.updatedis 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 withcode=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 withcode=422and 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
PENDINGand is reviewed before it completes. See Create Refund. - Suspended accounts cannot take payments.
/payments/createand/payments/checkoutreturncode=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/createand/payments/checkouttogether, unless agreed otherwise. Past that, the request is refused with HTTP429andcode=4001(tooManyRequests), and no order is created: wait a moment and retry with the samemerchant_order_no. Queries, refunds and payouts are not counted. PAYPALandPIXare not currently available. They are accepted by validation and then rejected withcode=3003. Payouts are available forCASH_APPonly: to a Cash App$cashtag, inUSD, once payouts are enabled for your account. Other payout methods returncode=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+Ncounts 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 itsT+Ndate (for example the following Friday). Each order's settle date is shown with the order.
