> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # Trade ## Event List | **Event Name** | **Event Type** | **Trigger Condition** | **Data Structure** | | :----------------------------------- | :------------------------ | :------------------------------- | :--------------------------- | | Trade order created | v2.trades.created | When a trade order created | [Trade](/en/webhook/trade-2) | | The transaction order payment failed | v2.trades.payment\_failed | When a trade order is paid fails | [Trade](/en/webhook/trade-2) | | Trade order payment Succeeded | v2.trades.succeeded | When a payment is successful | [Trade](/en/webhook/trade-2) | ## 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\ | 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 ```mermaid theme={null} 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 ```json v2.trades.created theme={null} { "id": "572677246926464036", "type": "v2.trades.created", "created": "2025-10-28T06:54:55Z", "data": { "metadata": {}, "return_url": "https://checkout.sandbox.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": "", "paid_at": null, "payment_token": "", "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": "requires_payment_method", "invoice_id" : "" } } ``` ```json v2.trades.payment_failed theme={null} { "id": "593722365515409383", "type": "v2.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": "Other error" }, "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": "" } } ``` ```json v2.trades.succeeded theme={null} { "id": "572677246926464036", "type": "v2.trades.succeeded", "created": "2025-10-28T06:54:55Z", "data": { "metadata": {}, "return_url": "https://checkout.sandbox.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" } } ```