# 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:

| 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](https://www.hansapay.io/docs/what-to-expect)) |
| `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 | Email |
| `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:

```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": "john@example.com",
    "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`, 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:

| 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:

```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": "buyer@example.com",
    "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`

| 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

```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

| 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](https://www.hansapay.io/docs/payments#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_address` and `shipping_address` whenever 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`, `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:

| 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 `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"
  }
}
```
