> ## 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.

# Object

Trade entity field reference.

| Field                   | Type               | Desc                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| trade\_id               | string             | Trade ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| access\_no              | string             | Third-party access number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| merchant\_id            | string             | Merchant ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| amount                  | string             | Payment amount, truncated to two decimal places                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| currency                | string             | Currency                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| customer\_id            | string             | Platform customer ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| callback\_url           | string             | Webhook notification callback URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| metadata                | map\[string]string | A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| last\_payment\_error    | LastPaymentError   | Last payment error information, if this field has a value, it indicates payment failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| next\_action            | NextAction         | Next action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| order\_id               | string             | Third-party order number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| last\_trans\_id         | string             | Order transaction ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| paid\_at                | string             | Payment success time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| payment\_mode           | string             | Payment business mode:<br />subscription: Initial subscription payment, requires collecting customer payment information, pass `payment_method_data` field, returns `payment_token` for subsequent subscription renewals upon successful payment<br />recurring\_payment: Subscription renewal payment, requires passing `payment_token` to complete payment, no need to collect user payment information                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| payment\_token          | string             | Payment token returned for subscription payment, used for subsequent subscription renewals                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| payment\_method         | string             | Payment method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| payment\_channel        | string             | Payment channel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| return\_url             | string             | Redirect page after payment channel accepts successfully in scenarios like 3DS redirect payment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| trade\_status           | string             | Payment status:<br />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.<br />payment\_failed: 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.<br />processing: The payment has been submitted by the customer and is being processed by the provider. The result is pending — possibly under risk review, bank processing, or delayed settlement.<br />succeeded: The payment has been confirmed successfully by the provider, and the funds have been credited.<br />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. |
| txn\_time               | string             | Trade initiation time, time when client initiates the interface                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| created\_at             | string             | Creation time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| refund\_status          | string             | Refund status:<br />no\_refund: No refund<br />partially\_refunded: A partial refund has been successfully issued, and the refunded amount is less than the total trade order value.<br />refunded: The full amount of the trade order has been successfully refunded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| total\_refunded\_amount | string             | Refund amount, truncated to two decimal places                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| session\_id             | string             | Session id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| session\_url            | string             | Session url                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| refer\_info             | ReferInfo          | Source information of the customer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| order\_type             | string             | Order types generated under different purchase or billing scenarios:<br />onetime\_payment: The trade order is created for a one-time payment request.<br />subscription: The trade order is created for initiating a subscription payment request.<br />recurring\_payment: The trade order is created by the Subotiz subscription renewal service.<br />token\_payment: The trade order is created when the merchant charges a customer using an existing subscription contract token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| line\_items             | LineItem\[]        | The line items purchased by the customer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| discounts               | Discounts          | Discounts applied to the trade, including all discount information for this trade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| closed\_at              | string             | Trade closed time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| closed\_reason          | string             | The reason for the order being closed<br />timeout: Payment timed out<br />renewal\_failed: Subscription renewal failed (including retries)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| first\_source\_channel  | string             | The source where this checkout session was initially created                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| last\_source\_channel   | string             | The source where this checkout session was last accessed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| billing\_address        | BillingAddress     | The customer's billing address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

## ReferInfo

| Field         | Type   | Desc                                                                                                                                                                                                                                                         |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| country\_code | string | The country code of the client (ISO 2 format)                                                                                                                                                                                                                |
| ip            | string | The customer's IP address                                                                                                                                                                                                                                    |
| device        | string | The type of the customer's equipment<br />pc: Refers to the types of personal computer devices including desktops and laptops.<br />mobile: Refers to portable device types that have wireless connection capabilities and include smart phones and tablets. |
| user\_agent   | string | The customer's user agent                                                                                                                                                                                                                                    |

## NextAction

| Field    | Type               | Desc                                                            |
| -------- | ------------------ | --------------------------------------------------------------- |
| type     | string             | Type of next action required by client:<br />redirect: Redirect |
| redirect | NextActionRedirect | Redirect information                                            |
| client   | NextActionClient   | Client operation information                                    |

## NextActionRedirect

| Field | Type   | Desc         |
| :---- | :----- | :----------- |
| url   | string | Redirect URL |

## NextActionClient

| Field               | Type   | Desc                               |
| :------------------ | :----- | :--------------------------------- |
| confirm\_url        | string | Confirm payment URL                |
| apple\_pay\_session | string | ApplePay session data for creation |

## LastPaymentError

| Field   | Type   | Desc                                           |
| :------ | :----- | :--------------------------------------------- |
| code    | string | System returned transaction return code        |
| message | string | System returned transaction return description |

## LineItem

| Field       | Type   | Desc                                            |
| :---------- | :----- | :---------------------------------------------- |
| product\_id | string | The product ID of the item being purchased      |
| price\_id   | string | The price ID associated with the purchased item |
| price       | string | The price before any discounts are applied      |
| quantity    | int    | The quantity of products being purchased        |

## 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                 |

## BillingAddress

| Field             | Type   | Desc                                                |
| :---------------- | :----- | :-------------------------------------------------- |
| name              | string | Recipient's full name (e.g: John Smith)             |
| address\_line1    | string | Address line 1, primary street address              |
| address\_line2    | string | Address line 2, additional address information      |
| country\_code     | string | Country code in ISO2 format (e.g: US, GB, CN)       |
| province\_code    | string | Province/state code (e.g: CA for California)        |
| city              | string | City name                                           |
| area              | string | Area/district/county name for more granular address |
| postal\_code      | string | Postal code/ZIP code, format varies by country      |
| phone             | string | Phone number without country code                   |
| phone\_area\_code | string | Phone country code (e.g: +1, +44, +86)              |
| email             | string | Email address for billing notifications and contact |