Event List

Event Name	Event Type	Trigger Condition	Data Structure
Trade Order Payment Succeeded	trades.succeeded	When a payment is successful	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 `requires_action`: Indicates the trade order requires additional customer action (e.g., 3DS authentication redirect). `processing`: Payment is being processed `succeeded`: Payment succeeded
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

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

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.

Trade Order Lifecycle

stateDiagram
    [*] --> requires_payment_method : Created
    requires_payment_method --> requires_action : Payment submitted & requires redirect
    requires_payment_method --> processing : Payment submitted & returned "processing" status
    requires_payment_method --> succeeded : Payment submitted & synchronously succeeded
    requires_action --> requires_payment_method : Redirect failed/timed out/canceled
    requires_action --> processing : Payment processing
    requires_action --> succeeded : Payment succeeded
    processing --> succeeded : Payment succeeded
    processing --> requires_payment_method : Payment failed
    succeeded --> [*]

Handling Instructions per Trade Status:

requires_payment_method: Indicates a payment failure scenario. No additional action is required for orders in this state.
requires_action: Indicates a redirect payment is in progress. This status is set after Subotiz submits payment information to the provider for a redirect-based flow. You must poll trade orders in this status until they transition to requires_payment_method (failed) or succeeded.
Processing: Indicates the payment is being processed asynchronously by the payment provider. You must poll trade orders in this status until they transition to requires_payment_method(failed) or succeeded.
succeeded: Indicates the payment is successful. No additional action is required.