API Reference

Create Order API

Use the Create Order API to generate a Payment Link, which will provide an HTML URL for completing the payment via a browser.

API Description

Request URL

https://gateway.wonder.app/api/galaxy/payment-link

Request Method

POST

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
total_amount	float	N	Transaction amount items
pre_auth	boolean	N	Instructions for conducting pre authorization transactions only
charge_fee	float	N	Charge fee
tips	float	N	Tips amount
currency	string(3)	Y	Currency (e.g., HKD, USD)
reference_number	string(32)	N	Unique internal order number in the merchant system
remark	string(255)	N	Remark for the order
line_items	object array	N	Information about the products
--id	integer	Y	SKU ID
--label	string(255)	Y	SKU name
--quantity	integer	Y	SKU quantity
--price	float	Y	SKU unit price
--total	float	Y	SKU total amount
--discount_total	float	Y	SKU discount amount
customer_id	string(32)	N	Customer ID
redirect_url	string(255)	N	URL to redirect after successful payment
callback_url	string(255)	N	URL for backend notification after state change

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Body (JSON):

without line items:

{
  "charge_fee": 2,
  "tips": 0,
  "currency": "HKD",
  "reference_number": "abc123456",
  "remark": "Test Payment Link",
  "redirect_url": "https://www.domain.com/redirect",
  "callback_url": "https://www.domain.com/callback"
}

with line items:

{
  "total_amount": 12,
  "charge_fee": 2,
  "tips": 1,
  "currency": "HKD",
  "reference_number": "abc1234567",
  "remark": "Test Payment Link",
  "redirect_url": "https://www.domain.com/redirect",
  "callback_url": "https://www.domain.com/callback",
  "line_items": [
    {
      "id": 1,
      "label": "Test Item",
      "quantity": 1,
      "price": 10,
      "total": 10,
      "discount_total": 0
    }
  ]
}

Link Type Differentiation

Link Type	Tag	Description
Sales Payment Link	pre_auth = false or undefined	Collect one-time sales payment for your sales invoices. Suitable for e-commerce purposes.
Pre-auth Payment Link	pre_auth = true	Collect your customer's card/wallet information, to later charge the customer. Suitable for future payment collection, after goods/services have been delivered/provided.

Response Parameters

Variable	Type	Required	Description
url	string(255)	Y	Payment URL

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": {
    "url": "https://s-stg.wonder.app/2SiNH4"
  }
}

Void Order API

Void the order before the order is paid.

API Description

Request URL

https://gateway.wonder.app/api/oms/b2b/open/payment/orders/reference/{reference_number}/void

Request Method

POST

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
reference_number	string(32)	Y	[path] Unique internal order number in the merchant system

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Body (JSON):

{}

Response Parameters

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": null
}

Refund Order API

Refund for the paid order.

API Description

Request URL

https://gateway.wonder.app/api/oms/b2b/open/payment/orders/reference/{reference_number}/refund

Request Method

POST

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
reference_number	string(32)	Y	[path] Unique internal order number in the merchant system
refund_reason	string(255)	N	[body] Reason for the refund
transactions_to_be_refunded	object array	N	[body] Array supporting fully and partial refunds
-- transaction_id	integer	Y	[body] Obtainable via Query Order API
-- amount	float	Y	[body] Refund amount
-- note	string(255)	N	[body] Refund note
-- payment_data	string(255)	N	[body] Payment data

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Body (JSON):

{
  "refund_reason": "reason",
  "transactions_to_be_refunded": [
    {
      "amount": 0,
      "note": "string",
      "payment_data": "string",
      "transaction_id": 0
    }
  ]
}

Response Parameters

Variable	Type	Required	Description
number	string(24)	Y	Bindo order number
reference_number	string(32)	Y	Unique internal order number in the merchant system
correspondence_state	string(20)	Y	Paid state: unpaid/partial_paid/paid/over_paid/refunded
state	string(20)	Y	Order state: in_completed/voided/completed
initial_total	float	Y	Order amount
paid_total	float	Y	Payment amount
line_items	object array	Y	Order product information
- id	integer	Y	SKU ID
- label	string(255)	Y	SKU name
- quantity	integer	Y	SKU quantity
- price	float	Y	SKU unit price
- discount_total	float	Y	SKU discount total amount
sale_transactions	object array	N	Transactions. include refunded transactions
- id	integer	Y	Transaction ID
- amount	float	Y	Transaction amount
- currency	string(3)	Y	Currency
- success	boolean	Y
refund_transactions	object array		Refunded transactions
- id	integer	Y	Transaction ID
- amount	float	Y	Refunded amount
- currency	string(3)	Y	Currency
- success	boolean	Y
void_transactions	object array	Y	Voided transactions
- id	integer	Y	Transaction ID
- amount	float	Y	Voided amount
- currency	string(3)	Y	Currency
- success	boolean	Y

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": {
    "additional_documents": [
      "string"
    ],
    "auth_code": "string",
    "business_name": "string",
    "correspondence_state": "string",
    "created_at": "2023-04-25T07:16:33.551Z",
    "created_by": "string",
    "currency": "string",
    "custom_attributes": "string",
    "customer_country_code": "string",
    "customer_dial_code": "string",
    "customer_email": "string",
    "customer_linked_source_type": "string",
    "customer_name": "string",
    "customer_phone": "string",
    "customer_reference": "string",
    "delivery_date": "2023-04-25T07:16:33.551Z",
    "discount_total": 0,
    "due_date": "string",
    "fail_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "from": 0,
    "id": 0,
    "initial_normal_tax": 0,
    "initial_tax": 0,
    "initial_tips": 0,
    "initial_total": 0,
    "inventory_status": "string",
    "line_items": [
      {
        "discount_total": 0,
        "id": 0,
        "image_url": "string",
        "label": "string",
        "price": 0,
        "purchasable_type": "string",
        "purchase_id": "string",
        "quantity": 0,
        "total": 0
      }
    ],
    "note": "string",
    "notify_url": "string",
    "number": "string",
    "oms_delivery_note": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": 0,
      "email": "string",
      "name": "string",
      "note": "string",
      "phone": "string"
    },
    "paid_total": "string",
    "payment_link_url": "string",
    "reference_number": "string",
    "refund_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "return_url": "string",
    "sale_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "signatures": [
      {
        "encoded_signature": "string",
        "transaction_id": 0
      }
    ],
    "state": "string",
    "subtotal": 0,
    "surcharge_fee": 0,
    "type": "string",
    "unpaid_total": "string",
    "updated_at": "2023-04-25T07:16:33.551Z",
    "void_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ]
  }
}

Close Order API

Close the order after partial paid.

API Description

Request URL

https://gateway.wonder.app/api/oms/b2b/open/payment/orders/reference/{reference_number}/close

Request Method

POST

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
reference_number	string(32)	Y	[path] Unique internal order number in the merchant system

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Body (JSON):

{}

Response Parameters

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": null
}

Void Transaction

Before the completion or settlement of a transaction, a void operation can be performed. Whether a transaction can be voided can be determined through the "allow_void" field of the Query Order API.

API Description

Request URL

https://gateway.wonder.app/api/oms/b2b/open/payment/transaction/{transaction_id}/reference/{reference_number}/void

Request Method

POST

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
reference_number	string(32)	Y	[path] Unique internal order number in the merchant system
transaction_id	integer	Y	[path] Obtainable via Query Order API
payment_data	string(255)	N	[body] Payment data

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Body (JSON):

{
    "payment_data": "string"
}

Response Parameters

Variable	Type	Required	Description
number	string(24)	Y	Bindo order number
reference_number	string(32)	Y	Unique internal order number in the merchant system
correspondence_state	string(20)	Y	Paid state: unpaid/partial_paid/paid/over_paid/refunded
state	string(20)	Y	Order state: in_completed/voided/completed
initial_total	float	Y	Order amount
paid_total	float	Y	Payment amount
line_items	object array	Y	Order product information
--id	integer	Y	SKU ID
--label	string(255)	Y	SKU name
--quantity	integer	Y	SKU quantity
--price	float	Y	SKU unit price
--discount_total	float	Y	SKU discount total amount
sale_transactions	object array	N	Transactions. include refunded transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Transaction amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y
refund_transactions	object array		Refunded transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Refunded amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y
void_transactions	object array	Y	Voided transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Voided amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": {
    "additional_documents": [
      "string"
    ],
    "auth_code": "string",
    "business_name": "string",
    "correspondence_state": "string",
    "created_at": "2023-04-25T07:16:33.551Z",
    "created_by": "string",
    "currency": "string",
    "custom_attributes": "string",
    "customer_country_code": "string",
    "customer_dial_code": "string",
    "customer_email": "string",
    "customer_linked_source_type": "string",
    "customer_name": "string",
    "customer_phone": "string",
    "customer_reference": "string",
    "delivery_date": "2023-04-25T07:16:33.551Z",
    "discount_total": 0,
    "due_date": "string",
    "fail_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "from": 0,
    "id": 0,
    "initial_normal_tax": 0,
    "initial_tax": 0,
    "initial_tips": 0,
    "initial_total": 0,
    "inventory_status": "string",
    "line_items": [
      {
        "discount_total": 0,
        "id": 0,
        "image_url": "string",
        "label": "string",
        "price": 0,
        "purchasable_type": "string",
        "purchase_id": "string",
        "quantity": 0,
        "total": 0
      }
    ],
    "note": "string",
    "notify_url": "string",
    "number": "string",
    "oms_delivery_note": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": 0,
      "email": "string",
      "name": "string",
      "note": "string",
      "phone": "string"
    },
    "paid_total": "string",
    "payment_link_url": "string",
    "reference_number": "string",
    "refund_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "return_url": "string",
    "sale_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "signatures": [
      {
        "encoded_signature": "string",
        "transaction_id": 0
      }
    ],
    "state": "string",
    "subtotal": 0,
    "surcharge_fee": 0,
    "type": "string",
    "unpaid_total": "string",
    "updated_at": "2023-04-25T07:16:33.551Z",
    "void_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:16:33.551Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:16:33.551Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ]
  }
}

Query Order

API Description

Request URL

https://gateway.wonder.app/api/oms/b2b/open/payment/orders/reference/{reference_number}

Request Method

GET

Request Parameters

Variable	Type	Required	Description
business_id	string(36)	Y	[header] Business ID
reference_number	string(32)	Y	[path] Unique internal order number in the merchant system

Request Example

Header:

{
  "x-app-slug": "3pDZ5B",
  "x-app-key": "deb512b8-00b3-4cb9-a1b8-45d564a5fb81",
  "authorization": "Bearer XXXXXXXXXXXXXXXX",
  "x-p-business-id": "c3cc84fe-b1c3-11ec-a3d9-42010aaa001d"
}

Response Parameters

Variable	Type	Required	Description
number	string(24)	Y	Bindo order number
reference_number	string(32)	Y	Unique internal order number in the merchant system
correspondence_state	string(20)	Y	Paid state: unpaid/partial_paid/paid/over_paid/refunded
state	string(20)	Y	Order state: in_completed/voided/completed
initial_total	float	Y	Order amount
paid_total	float	Y	Payment amount
line_items	object array	Y	Order product information
--id	integer	Y	SKU ID
--label	string(255)	Y	SKU name
--quantity	integer	Y	SKU quantity
--price	float	Y	SKU unit price
--discount_total	float	Y	SKU discount total amount
sale_transactions	object array		Transactions. include refunded transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Transaction amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y
-- allow_void	boolean	Y	Transaction can be voided or not
-- allow_refund	boolean	Y	Transaction can be refuded or not
-- refunded_amount	boolean	Y	Refunded amount
refund_transactions	object array	N	Refunded transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Refunded amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y
void_transactions	object array	N	Voided transactions
-- id	integer	Y	Transaction ID
-- amount	float	Y	Voided amount
-- currency	string(3)	Y	Currency
-- success	boolean	Y

Response Example

Body (JSON):

{
  "code": 200,
  "message": "successful",
  "data": {
    "additional_documents": [
      "string"
    ],
    "auth_code": "string",
    "business_name": "string",
    "correspondence_state": "string",
    "created_at": "2023-04-25T07:15:03.222Z",
    "created_by": "string",
    "currency": "string",
    "custom_attributes": "string",
    "customer_country_code": "string",
    "customer_dial_code": "string",
    "customer_email": "string",
    "customer_linked_source_type": "string",
    "customer_name": "string",
    "customer_phone": "string",
    "customer_reference": "string",
    "delivery_date": "2023-04-25T07:15:03.222Z",
    "discount_total": 0,
    "due_date": "string",
    "fail_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:15:03.222Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:15:03.222Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "from": 0,
    "id": 0,
    "initial_normal_tax": 0,
    "initial_tax": 0,
    "initial_tips": 0,
    "initial_total": 0,
    "inventory_status": "string",
    "line_items": [
      {
        "discount_total": 0,
        "id": 0,
        "image_url": "string",
        "label": "string",
        "price": 0,
        "purchasable_type": "string",
        "purchase_id": "string",
        "quantity": 0,
        "total": 0
      }
    ],
    "note": "string",
    "notify_url": "string",
    "number": "string",
    "oms_delivery_note": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": 0,
      "email": "string",
      "name": "string",
      "note": "string",
      "phone": "string"
    },
    "paid_total": "string",
    "payment_link_url": "string",
    "reference_number": "string",
    "refund_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:15:03.223Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:15:03.223Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "return_url": "string",
    "sale_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:15:03.223Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:15:03.223Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ],
    "state": "string",
    "subtotal": 0,
    "surcharge_fee": 0,
    "type": "string",
    "unpaid_total": "string",
    "updated_at": "2023-04-25T07:15:03.223Z",
    "void_transactions": [
      {
        "3ds": "string",
        "acquirer_response_body": "string",
        "amount": 0,
        "created_at": "2023-04-25T07:15:03.223Z",
        "currency": "string",
        "extra": {
          "credit_card_type": "string",
          "first_6_digits": "string",
          "holder_name": "string",
          "last_4_digits": "string",
          "number": "string"
        },
        "from": "string",
        "id": 0,
        "is_pending": true,
        "note": "string",
        "payment": "string",
        "payment_data": "string",
        "payment_method": 0,
        "reference_id": "string",
        "success": true,
        "voided_at": "2023-04-25T07:15:03.223Z",
        "allow_void": false,
        "allow_refund": false,
        "refunded_amount": 0
      }
    ]
  }
}

Order Webhook Notification

When an order is created, paid, voided, or refunded, and a callback URL is configured, you will receive this notification.

API Description

Request Method: POST

Callback URL: This link is set through the "callback_url" request parameter in the Create Order API. Please ensure that the callback URL can be accessed externally. Example of a callback URL: "https://pay.doman.com/callback".

Notification Rules

1. During the notification integereraction with the backend, if the response received does not comply with the specification or exceeds the time limit, the platform considers the notification failed and will periodically reissue the notification through certain strategies to increase the success rate of notification as much as possible, but it does not guarantee that the notification will ultimately be successful. (Notification frequency is 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - a total of 24h4m)
2. In case of unclear order status or no webhook result notification received, it is recommended to proactively call the Query Order API to confirm the order status.

Notification Parameters

Variable	Type	Required	Description
app_slug	string(255)	Y	App slug(x-app-slug)
nonce	string(255)	Y	Random value
sign	string(255)	Y	Signature value
action	string(20)	Y	Action:order.created/order.paid/order.payment_failure/order.voided/order.refunded/transaction.voided
order	object	Y	Order object
-- number	string(24)	Y	Order number
-- reference_number	string(32)	Y	Integerernal order number
-- store_id	integer	Y	Store ID
-- business_id	string(36)	Y	Business ID
-- auth_code	string(255)	Y	Order authorization query code
-- paid_total	float	Y	Paid amount
-- unpaid_total	float	Y	Unpaid amount
-- state	string(20)	Y	Order status: invoiced/in_completed/voided/completed
-- correspondence_state	string(20)	Y	Payment status: unpaid/partial_paid/paid/refunded

Notification Example

Body(JSON):

{
  "app_slug": "3pDZ5B",
  "nonce": "H0AKlYqYFtfs",
  "sign": "34CAAF32B636A068A4080427F68960A4",
  "action": "order.created",
  "order": {
    "id": 100,
    "store_id": 1,
    "business_id": "84cf5702-b292-11ec-a3d9-42010aaa001d",
    "number": "201801312107321291062222",
    "reference_number": "1000026",
    "state": "completed",
    "correspondence_state": "paid",
    "auth_code": "htxnD0YhUJYoZjA",
    "paid_total": 100,
    "unpaid_total": 0
  }
}

Signature verification steps

When receiving a webhook request, signature verification is required to ensure the legitimacy of the request source. The following is the process of signature verification:

Step 1: Sort the parameters of the order object, nonceand app_key alphabetically by parameter name, and concatenate the parameter names and their values integero a string in the format "parameter1=value1&parameter2=value2&..."

Step 2: Calculate the hash value of the string using MD5 function, and compare the calculated hash value to the signature value provided in the API request.

Step 3: If the two values match, the signature is valid and the request can be processed. If the values do not match, the request should be rejected as unauthorized.

Please note the following important rules:

• The API may add fields, and the verification process must support these additional fields.

Example：

app_key: deb512b8-00b3-4cb9-a1b8-45d564a5fb81 (x-app-key)
nonce: H0AKlYqYFtfs
sign: 34CAAF32B636A068A4080427F68960A4

Step 1: Sort the parameters of the order object, nonceand app_key alphabetically by parameter name, and concatenate the parameter names and their values.

stringTemp = "app_key=deb512b8-00b3-4cb9-a1b8-45d564a5fb81&auth_code=htxnD0YhUJYoZjA&business_id=84cf5702-b292-11ec-a3d9-42010aaa001d&correspondence_state=paid&id=100&nonce=H0AKlYqYFtfs&number=201801312107321291062222&paid_total=100&reference_number=1000026&state=completed&store_id=1&unpaid_total=0"

Step 2: Calculate the MD5 hash value and verify it

signValue = MD5(stringTemp).toUpperCase()
output: 34CAAF32B636A068A4080427F68960A4

if (signValue == sign) {
   // TODO
}

The relationship between action and order/payment state

action	state(order state)	correspondence_state(payment state)
order.created	invoiced	unpaid
order.paid(partial)	in_completed	partial_paid
order.paid(fully)	completed	paid
order.payment_failure	invoiced	unpaid
order.voided	voided	unpaid
order.refunded(partial)	in_completed	partial_paid
order.refunded(fully)	completed	refunded
transaction.voided(parital)	in_completed	partial_paid
transaction.voided(fully)	completed	refunded

Notification Response

Successful reception: HTTP response status code must return 200 without returning response message.

Failed reception: HTTP response status code must return 5XX and return response message in the following format:

Variable	Type	Required	Description
code	string	Y	Error code, SUCCESS for successful receipt by the clearing institution, other error codes for failure.
message	string	Y	Response information, if not empty, is the reason for the error. Example Value: FAIL

Example：

{  
    "code": "FAIL",
    "message": "error message"
}

Whitelist IP

If you have firewall requirements and need to allow specific IP addresses to access your production environment, please add the following IP addresses to your firewall whitelist:: 119.8.39.23/32 119.8.232.135/32

Make sure to regularly update and maintain this whitelist to ensure that your integration with Wonder remains secure and operational. Additionally, it's a good practice to consult Wonder's documentation or support for the most up-to-date list of IP addresses that should be allowed through your firewall.

API Rejection Reason

API Gateway Rejection Code

HTTP Code	DESCRIPTION
400	Invalid Parameter
500	Internal Server Error

Payment Link Rejection Code

NO.	Code	DESCRIPTION
1	100001	Invalid Parameter
2	100102	Invalid Currency. Store does not support currency
3	100201	Store Does Not Exist
4	100301	Order Does Not Exist
5	100302	Order Has Already Paid
6	100303	Order Has Already Voided
7	100304	Order Has Already Overdue
8	100305	Invalid Currency. Order does not support currency
9	100307	Order Can't be Voided
10	100308	Order Can't be Refund
11	100309	Reference Number Has Already Existed
12	100310	Transaction Amount Error
13	100311	Order Can't be Close
14	100312	Order Has Already Closed
15	100401	Transaction Does Not Exist
16	100403	Transaction Can't be Voided
17	100701	Payment Failed
18	100704	Invalid Payment Method
19	400000001	Invalid Parameter
20	400000002	The auth app does not exist
21	400002000	Invalid app secret key