Payment Management

You may use different products to receive payments, yet the same APIs are available for payment operations and management. You can utilize identical interfaces to query transaction status or process refund/void. This document will walk you through various data models and operation methods in detail.

Order

Field	Required	Description
Number	`Output`	Wonder-generated unique order number. Use this to map with your system.
Reference_number	`Yes`	Your system's unique ID. We strongly recommend always passing this field so you can correlate orders across systems.
Charge_fee	`Yes`	The total amount charged to the customer (e.g. `21.00`).
Tips	`No`	Additional tip amount paid by the customer. Defaults to "0.00" .
Currency	`Yes`	ISO currency code (e.g. `HKD`). Determined by the merchant's configuration.
Due_date	`No`	A date in `YY-MM-DD` format. Orders not completed by this date are automatically voided. Uses the business timezone.
Timeout	`No`	Auto-expire the payment link after a set number of seconds from the first time the customer opens it. Contains `timer` (seconds) and `redirect_url` (redirect on expiry). Only applies to Payment Link orders.
Callback_url	`No`	URL where Wonder sends webhooks to your system when order or payment state changes.
Redirect_url	`No`	Where the Payment Link page redirects after the customer completes (or abandons) payment.
Note	`No`	Free-text note. Max 255 characters.
Source	`Output`	Marks which platform generated the order (see Order sourceDOC below).
Line_items	`No`	Detail items in the order(see Line itemsDOC below).

INFO

Order expiry: A Payment Link should not stay valid forever. Use due_date (YY-MM-DD format) to auto-void the order after a calendar date, or timeout with timer (seconds) + url (redirect URL) to expire the link from the moment the customer first opens it.

Order lifecycle

An order progresses through a defined set of states. Understanding these states is critical for correct integration.

State

State	Meaning	Operations allowed
Invoiced	Order created, awaiting payment. May have partial transactions.	`Pay`,`Void`,`Update`.
Completed	Fully paid and closed.	Query only.
Voided	Cancelled. Cannot be modified or re-opened.	Query only.

Correspondence_state (Payment Status)

State	Meaning
Unpaid	No successful transactions yet, or all transactions have been voided/refunded.
Partial_paid	Total paid is less than `charge_fee`.
Paid	Total paid equal`charge_fee`.
Over_paid	Total paid exceeds `charge_fee`.
Refunded	All payments have been fully refunded.

INFO

An order starts as Invoiced / Unpaid. Each successful payment advances the correspondence state. Voiding all transactions returns it to Unpaid. A full refund sets it to Refunded.

Order source

The source field records which Wonder product or channel generated the order.

Source	Description
Bindo POS	Invoice and payment created through Bindo POS.
Wonder platform	Created via Online Payment Link.
Wonder Paystation Link	Created through Wonder Paystation Link.
Wonder Soft POS	Created through Virtual Terminal on Wonder App.
Wonder POS	Created through Wonder mPOS.
Wonder Integration Link	Created through Wonder Integration Link.
Wonder Payment SDK	Created through Wonder Payment SDK.
Wonder OpenAPI	Created through Wonder OpenAPI.

Line items

Line items describe what the customer is paying for. They are displayed on the Payment Link page and included in order data. You can have up to 100 line items per order.

Field	Required	Description
Purchasable_type	`Yes`	The type of this item. Supported values: `Listing`.
Label	`No`	Product name shown to the customer on the Payment Link page. Max 255 characters.
Price	`Yes`	Price per unit.
Quantity	`Yes`	Number of units.
Total	`Yes`	Line total — should equal `Price` × `Quantity`.
UUID	`No`	Your system's unique ID for this line item (UUID V4).

WARNING

When you manually provide line_items, the sum of all charge line item total values must equal the order's charge_fee.

json


{
"order" : {
  "reference_number" : "<Your system unique number>",
  "charge_fee" : "40",
  "line_items" : [
    {
      "purchasable_type" : "Listing",
      "label" : "<Your Product Name Here>",
      "price" : "10.0",
      "quantity" : 2,
       "total" : "20"
    }]
}

Transaction

A transaction records a single payment operation. Every charge, refund, authorization, and capture creates a new transaction entry within the order.

Field	Required	Description
type	`Output`	Transaction type: `Sales` (one-time payment), `Authorization` (pre-auth hold), `Capture` (finalized auth), or `Refund`.
Amount	`Output`	The transaction amount.
Success	`Output`	Whether the transaction succeeded.
Is_pending	`Output`	`true` for async payment methods where the final result is not yet known. Use the query order apiAPI to confirm the outcome.
Captured	`Output`	For pre-authorization transactions — has this authorization been captured?
Allow_void	`Output`	Whether this transaction can be voided. Typically true before day-end settlement.
Allow_refund	`Output`	Whether this transaction can be refunded. Typically true after day-end settlement
Payment_method	`Output`	The payment method used(eg.`Visa`,`Alipay`).
Payment_data	`Output`	Payment-method-specific details such as card `last_4_digits`, `acquirer_info`, `RRN`, `auth_code`. Content varies by payment method.
Original_transaction_uuid	`Output`	For `Capture` and `Refund` transactions — the UUID of the original authorization or sales transaction.

Transaction types

Type	Behavior
Sales	One-time immediate payment.
Authorization	Funds are frozen but not captured.
Capture	Finalizes a previous Authorization.
Refund	Returns funds to the customer.

Payment modes

Mode	Typical use case	Transaction type	Trigger	Flow & Notes
One-time payment	Standard e-commerce checkout, invoice payment, in-store purchase — the customer pays the full amount upfront.	`Sales`	Create an order with the final `charge_fee`; no extra flags needed.	1. Create the order with the exact `charge_fee`. 2. Customer completes payment via any channel. 3. On success, the order's `correspondence_state` becomes `paid`.
Pre-authorization	Hotel deposits, car rentals, tab-based orders — the final amount is determined after the service is delivered.	`Authorization`-->`Capture`	Set `is_only_pre_auth = true` when creating the order.	1. Authorize: Place a hold on the customer's card for the estimated amount. Funds are frozen but not captured. 2. Capture: Call the Capture API with the final amount. A Capture transaction is created, linked to the Authorization via `original_transaction_uuid`. 3. Optionally set `capture.close_order = true` to finalize the order as `Paid`. 4. Not all payment methods support pre-authorization. On Payment Link with `is_only_pre_auth = true`, unsupported methods are hidden.

Create orderAPI

Create an order with charge_fee, currency, and reference_number. Add with_payment_link = true to get a shareable Payment Link URL in the response. Optionally pass customer_uuid to link the order to a known customer and enable saved-card checkout.

Query an orderAPI
Query order listsAPI
Query transaction listsAPI

Look up an order by its number, reference_number or transaction_uuid. Recommended as a fallback when you haven't received a webhook, or to sync order data into your system. You can also query order lists and transaction lists using the advanced query DSLDOC for filtering and pagination.

Edit an orderAPI

Modify an existing order — change amount, line_items, or restrict which payment_method appear on the Payment Link page via payment_method_option. Voided orders cannot be updated.

Void an orderAPI

Void an order before settlement. Check allow_void first

Close an orderAPI

Cancel an entire order. Only possible when the order has no successful transactions (unpaid state). Or when the order is in partial_paid / over_paid, you can mark the order as paid via the close API.

Void a transactionAPI

Cancel a specific transaction before settlement. Check allow_void first. Use this for same-day reversals; for post-settlement reversals, use Refund.

Refund a transactionAPI

Return funds to the customer after settlement. You can issue partial refunds and refund a transaction multiple times up to its full amount. Always check allow_refund first.

Capture a transactionAPI

Finalize a pre-authorization transaction. Pass capture.amount and optionally set capture.close_order = true to update the order amount and close it as fully paid.

Check transaction statusAPI

For some payment methods, the result of the transaction is fetched asynchronously, and you can check the final result of the payment after initiating the transaction via this API.