Order management

Order Management API allows to create / get / void / refund orders (or transactions)

Models

Order

• Number: Wonder gateway unique order number. This is a best practice for mapping with your system.
• Reference Number: A unique number of third-party system, like your POS order id.
• Due Date: Payment termination time, if the order is not completed within the specified time, the order will be voided.
• Charge Fee: Order amount charged to the customer.
• Tips: Additional tips to be paid by customers.
• Callback URL: When the order/payment status changes, a webhook will be sent to this url.
• Redirect URL: When the Payment Link ends the payment (either successfully or unsuccessfully) it redirect to this url.
• Note: Any string, but it needs to be less than 255 characters.
• Currency: Standard payment currency code.
• Line Item: Order details
• Source: Marks the platform from which the order or transaction was generated

Order source

Source	Comment
Bindo POS	Invoice and payment created through Bindo POS
Wonder Platform	Invoice and paument created via Online Payment Link
Wonder Paystation Link	Invoice and payment created through Wonder Paysation Link
Wonder Soft POS	Invoice and payment created through Virtual Terminal on Wonder App
Wonder POS	Invoice and payment created through Wonder mPOS
Wonder Integration Link	Invoice and payment created through Wonder Integration Link
Wonder Payment SDK	Invoice and payment created through Wonder Payment SDK
Wonder OpenAPI	Invoice and payment created through Wonder OpenAPI

State

State	Comment
invoiced	Order created.
voided	Order voided. You can not do any operations after voided.
completed	Order is completed and closed with full payment

Correspondence State

Correspondence State	Comment
authorized	Credit card authorized
paid	Order already full paid
over_paid	Sum of all successful transactions over order amount
partial_paid	Sum of all successful transactions less than order amount
unpaid	Order doesn't have any successful transaction
refunded	Order has been fully refunded, for partial refunds, it will be partial_paid

Line Items

line item represents the details of the item in the order.

• Purchasable Type: Detailed types, enumerated types, support for parameters such as Charge, Tips, Listing, etc.
• Purchase ID: Just for purchasable_type = Listing, wonder inventory system id.
• Label: Product name for displaying to customers.
• Price: Product price
• Quantity: Product quantity
• Total: total = price * quantity
• UUID: The unique line item id in your system, not required.

If you don't need to show your customers the specific content of the paid item, then you can leave this parameter unspecified and the backend will generate it automatically.

If you don't have access to Wonder Inventory Management System yet, but still want to display product details, you can use the following format for reference:

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

danger

When you choose to manage the line item yourself, note that the charge_fee needs to be the same as the sum of the Charge line item.

---

Transaction

Transaction records

• Type: Transaction type.
• UUID: The uuid field can be passed in the payment api, must be UUID V4 compliant.
• Currency: The transaction currency.
• Amount: The transaction amount
• Is Pending: Whether the payment is in the PENDING state. Some of the payment methods are asynchronous and require the Query Order API to detect the final payment result.
• Captured: For a pre-authorization transaction, has this pre-authorization captured.
• Allow Void: Whether to allow void.
• Allow Refund: Whether to allow refunds.
• Payment Method: Payment methods for transactions. Please refer to Supported payment methods
• Original Transaction UUID: The original transaction of capture or refund transaction.

TransactionType

Transaction type represents different payment behaviors.

Transaction Type	Comment
Sales	One-time payment
Authorization	Credit card authorized transaction
Capture	Captured an authroized transaction
Refund	Refunded a sales or authorized transaction

---

Payment

Regardless of which product is used for integration, for payments it always includes the following behaviors.

One-time Payment

One time payment is a method of receiving a known amount of money directly from the customer. Its background is that the final amount of the order is already calculated when the customer initiates the transaction.

For a one-time payment, the field transactions.type will be Sales.

Each Sales transaction will have a record in order.transactions.

Pre-authorization Payment

Unlike one-time payment, pre-authorization is performed in two steps.

• Authorization: An authorization transaction is initiated, and although an amount is entered in the authorization transaction, it does not represent the final amount of the transaction, and the amount in the authorization transaction will only be frozen in the client's bank (Wallet) and will not be cleared to any third party.
• Capture: When the transaction is Authorized, you can use the Capture API to complete the Captured, Captured amount is the final amount of this payment.

Both Authorization and Capture are included in order.transactions, and for Capture transactions, the transaction.original_transaction_uuid field is the corresponding Authorization uuid of the transaction

---

Create an order

Create an unpaid order through the Order Creation API, use Payment Link / Payment SDK / Payment ECR and other payment scenarios to allow guests to make payments.

Please refer to Create Order API

---

Create a payment link

Use Create Order API, and add with_payment_link=true to Query param, payment_link will be returned in the response.

---

Update an exists order

After the order has been created, you can use the Update Order API to modify the data in the order again.

danger

If the order has already been voided, no modifications are allowed.

Query an order

Getting the status of an order in real time via the Query Order API is usually applicable:

• After creating an order, checking if the payment was returned
• Synchronizing Wonder Order data to your system

info

In addition to using Order Number and Order Reference Number for query, the function of using Transaction UUID for order query has been added. You only need to choose one or the other, order and transaction object.

Please refer to Query Order API

---

Void an transaction

Void a transaction that has not been fulfilled or before setttlement. Whether this transaction can be void, you can check the Query Order API by allowed_void field.

Typically, void transactions are allowed to be initiated before the day end.

Please refer to Void transaction API

---

Void an order

Allow void only if the order is in the unpaid state, consistent with the void transaction API, but without passing the transaction parameter.

Please refer to Void Order API

---

Make a transaction refund

Refund a transaction that allows you to refund a previously created charge that isn't refund yet. Typically, only after settlement can be use this API to do refund , otherwise, it should use Void transaction API. You can optionally refund only a part of charge, and you can do multiple times until the entire payment has been refunded.

Please check transaction.allow_refund via Get Order API first.

In contrast to Void transaction, a refund allows for the following after day end.

Capture pre-authorization transaction

Once you've completed the pre-authorization, you can captured the transaction via the Capture API.

This API has two modes to affect order behavior, in the request body if capture.close_order is true, capture.amount will be updated to the amount of the order, so if capture.close_order is true, then captured After that the order is paid.

Please refer to Capture transaction API

Order webhook

When creating an order, you are allowed to specify the callback_url parameter, which will send data to this address when the order changes. The data format is consistent with the Query Order API.

Please refer to Webhook check webhook details.

Data Flow

In order to better understand the data flow of a transaction, we drafted a relatively complex case.

Order Reference Number	Order Initial Total	Order Correspondence State	Transaction uuid	Transaction Type	Transaction Amount	Transaction Success	Transaction Voided	Transaction Original UUID	Action
2024050100000001	100	unpaid	-	-	-	-	-	-	After order created
2024050100000001	100	partial_paid	37b56236-5d86-44c2-8baa-200568036650	Sales	40	true	false	-	After successful $40 payment
2024050100000001	100	partial_paid	1b6e8ae1-0f1b-4e2b-83e8-27b3e1b6f951	Sales	60	false	false	-	After failed $60 payment
2024050100000001	100	paid	9f9a1f4c-98c4-4e95-8e3a-2c8d058c42a7	Sales	60	true	false	-	After success $60 payment
2024050100000001	100	partial_paid	9f9a1f4c-98c4-4e95-8e3a-2c8d058c42a7	Sales	60	true	true	-	After voided the successful $40 payment
2024050100000001	100	unpaid	a2e2f43e-b4d7-4b16-858a-9055bfb2c8d1	Refund	40	true	false	37b56236-5d86-44c2-8baa-200568036650	After refunded the $60 payment
2024050100000001	100	unpaid	5873b6b4-5ad6-46b9-92e8-63be11c4b8eb	Authorization	50	true	false	-	After authorized
2024050100000001	100	paid	3b3f2a24-96c6-4e0b-b2e8-1a27a97dc4be	Capture	100	true	false	5873b6b4-5ad6-46b9-92e8-63be11c4b8eb	After captured the authorized payment
2024050100000001	100	unpaid	6c5f34d3-9676-45db-9d6a-19b3d6c6b89e	Refund	100	true	false	3b3f2a24-96c6-4e0b-b2e8-1a27a97dc4be	After refund the captured payment