Event List

Event Name	Event Type	Trigger Condition	Data Structure
Trade Order Payment Succeeded	trades.succeeded	When a payment is successful	Trade
The transaction order payment failed.	trades.payment_failed	When a trade order is paid fails	Trade

Event Object

Field Name	Type	Description
trade_id	string	Trade order ID
access_no	string	Assigned access number for your platform
merchant_id	string	Merchant ID of your platform
amount	string	Payment amount, truncated to two decimal places.
currency	string	Currency of the transaction amount
customer_id	string	Customer ID
paid_at	string	The successful payment time of the trade order
metadata	map<string, string>	Passthrough metadata. Key ≤ 40 bytes, value length ≤ 500 bytes. Total size after JSON encoding must be ≤ 1024 bytes.
last_payment_error	PaymentError	Details of the last payment error. If this field has a value, it indicates `Payment failed`.
next_action	NextAction	Next action
order_id	string	Order ID from your platform
last_trans_id	string	Transaction ID for the order
payment_mode	string	Payment mode: `subscription`: Initial subscription payment. Requires collecting customer payment information via the payment_method_datafield. Returns a payment_token upon success for future renewals. `recurring_payment`: Subscription renewal payment. Requires a payment_token to complete the payment; no need to collect user payment information again.
payment_token	string	Payment tokens used for subscription renewal charges
payment_method	string	Payment method
payment_channel	string	Payment provider
return_url	string	URL to redirect to after successful processing in scenarios like 3DS authentication flows.
trade_status	string	Trade order status: `requires_payment_method`: Initial state `payment_failed`: Payment failed `processing`: Payment is being processed `succeeded`: Payment succeeded `closed`: Closed
txn_time	string	Trade initiation time when your client-side requests the API.
created_at	string	Creation time of the trade order
refund_status	string	Refund status: no_refund: No refunds issued partially_refunded: Partially refunded refunded: Fully refunded
total_refunded_amount	string	Total amount refunded, truncated to two decimal places
session_id	string	Checkout session ID from which the trade order originated
invoice_id	string	Unique identifier for the invoice
discounts	Discounts	Discounts applied to the trade, including all discount information for this trade

PaymentError

Field	Type	Desc
code	string	Error code for the transaction failure.
message	string	Error message describing the transaction failure.

NextAction

Field	Type	Desc
type	string	Type of action required from the client: `redirect`: Requires redirecting the customer to a URL
redirect	NextActionRedirect	Contains details for the redirect action

NextActionRedirect

Field	Type	Desc
url	string	The URL to redirect the customer to.

Discounts

Field	Type	Desc
current_period	CurrentPeriodDiscount[]	The current period's discount details

CurrentPeriodDiscount

Field	Type	Desc
discount_id	string	The unique identifier for the discount
discount_amount	string	The amount discounted
discount_code	string	The discount code used

Trade Order Lifecycle

stateDiagram-v2
  direction TB

  state "requires_payment_method" as RPM
  state "processing" as PROC
  state "payment_failed" as FAIL
  state "succeeded" as SUCC
  state "closed" as CLOSED

  RPM --> PROC: Payment processing
  RPM --> SUCC: Payment succeeded
  RPM --> FAIL: Payment failed

  PROC --> SUCC: Channel webhook notification succeeded
  PROC --> FAIL: Channel webhook notification failed

  FAIL --> PROC: Payment processing
  FAIL --> SUCC: After a retry, the payment succeeded.

  FAIL --> CLOSED: Renewal failed
  RPM --> CLOSED: Payment timeout

Handling Instructions per Trade Status:

requires_payment_method：Initial order status. The customer has not completed payment (may not have initiated it or is still in process), or a subscription renewal charge has been initiated but the result is not yet available.
payment_failed：Indicates a payment failure scenario, The provider declined the payment request due to reasons such as insufficient funds, failed card verification, or risk control restrictions. The customer can try again.
processing：Indicates the payment is being processed asynchronously by the payment provider, You must poll trade orders in this status until they transition to payment_failed or succeeded.
succeeded：Indicates the payment is successful, No additional action is required.
closed：Closed, The trade order is closed when its status is no longer expected to change positively, such as after a subscription renewal fails (after multiple retries) or when no payment result is returned for over 7 days.

Example

{
  "id": 572677246926464036,
  "type": "trades.succeeded",
  "created": "2025-10-28T06:54:55Z",
  "data": {
    "metadata": {},
    "return_url": "https://checkout.stg.subotiz.com/checkout/572677164911046667/return",
    "txn_time": "2025-10-28T06:54:52Z",
    "access_no": "77d52a21dc032b4",
    "amount": "30.00",
    "capture_method": "auto",
    "last_payment_error": null,
    "last_trans_id": "20251028572677234091900866",
    "paid_at": "2025-10-28T06:54:55Z",
    "payment_token": "pB_KO6Q***YU",
    "refund_status": "no_refund",
    "trade_id": "572677233903157186",
    "currency": "USD",
    "payment_method": "credit_card",
    "payment_channel": "shoplazzapayment",
    "total_refunded_amount": "0.00",
    "session_id": "572677164911046667",
    "merchant_id": "2816433",
    "customer_id": "547766341013094363",
    "order_id": "order_1761634475936438746",
    "payment_mode": "subscription",
    "trade_status": "succeeded",
		"invoice_id" : "547766341013094363"
  }
}

{
  "id": 593722365515409383,
  "type": "trades.payment_failed",
  "created": "2025-12-25T08:40:42Z",
  "data": {
    "access_no": "200010",
    "metadata": null,
    "last_trans_id": "",
    "paid_at": null,
    "session_id": "593722303875911656",
    "refund_status": "no_refund",
    "total_refunded_amount": "0.00",
    "customer_id": "537465921338359803",
    "last_payment_error": {
      "code": "100999",
      "message": "其他错误"
    },
    "order_id": "test_order_00111",
    "payment_token": "",
    "txn_time": "2025-12-25T08:40:36Z",
    "trade_status": "requires_payment_method",
    "trade_id": "593722338718003014",
    "amount": "50.00",
    "capture_method": "auto",
    "payment_channel": "shoplazzapayment",
    "return_url": "https://checkout.dev.subotiz.com/checkout/593722303875911656/return",
    "discounts": null,
    "merchant_id": "100010",
    "currency": "USD",
    "payment_mode": "subscription",
    "payment_method": "credit_card",
    "invoice_id": ""
  }
}