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

# Create Trade

> Create Trade



## OpenAPI

````yaml openapi/v1-en.yaml POST /api/v1/trades
openapi: 3.0.3
info:
  title: Subotiz API
  description: Subotiz OpenAPI
  version: 1.0.0
servers:
  - url: https://{api}.subotiz.com
    variables:
      api:
        default: api
security:
  - sec0: []
tags:
  - name: Subscription
    description: Subscription
  - name: Price
    description: Price
  - name: Trade
    description: Trade
  - name: Payment
    description: Payment
  - name: Checkout Session
    description: Checkout Session
  - name: Customer
    description: Customer
  - name: Customer Portal
    description: Customer Portal
paths:
  /api/v1/trades:
    post:
      tags:
        - Trade
      summary: Create Trade
      description: Create Trade
      operationId: v1-trade-create-trade
      parameters:
        - $ref: '#/components/parameters/HeaderRequestID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTradeResponse'
components:
  parameters:
    HeaderRequestID:
      name: Request-Id
      in: header
      description: The unique identifier of the request
      required: true
      schema:
        type: string
        default: 008e3967-a1b5-48bb-be14-d5bff5092e61
  schemas:
    CreateTradeRequest:
      required:
        - order_id
        - txn_time
        - server_name
        - payment_mode
        - amount
        - currency
      type: object
      properties:
        amount:
          type: string
          description: >-
            Payment amount, amount must be greater than 0, can be 0 only when
            using subscription payment method. Truncated to two decimal places
        currency:
          type: string
          description: >-
            Transaction currency corresponding to the amount, encoded according
            to ISO4217
        customer_id:
          type: string
          description: >-
            Subotiz customer ID, associate with existing customer in Subotiz,
            choose one with `customer_data` field, use this field when you need
            to associate with existing customer
        customer_data:
          allOf:
            - $ref: '#/components/schemas/CustomerData'
          description: >-
            Customer data, create customer object in Subotiz, choose one with
            `customer_id` field, use this field when you need to create new
            customer.
        metadata:
          type: object
          description: >-
            A set of key-value pairs that can be attached to an object, allowing
            you to store additional information in a structured format.
        order_id:
          type: string
          description: Third-party order ID
        payment_mode:
          type: string
          description: >-
            Payment business mode:

            - onetime_payment: One-time payment, requires collecting customer
            payment information, pass `payment_method_data` field.

            - subscription: Initial subscription payment, requires collecting
            customer payment information, pass `payment_method_data` field,
            returns `payment_token` for subsequent subscription renewals upon
            successful payment

            - recurring_payment: Subscription renewal payment, requires passing
            `payment_token` to complete payment, no need to collect user payment
            information
        payment_token:
          type: string
          description: >-
            Customer payment token, used for subscription renewal, required when
            using `recurring_payment` payment method.
        return_url:
          type: string
          description: >-
            Redirect page after payment channel accepts successfully in
            scenarios like 3DS redirect payment
        txn_time:
          type: string
          description: 'Trade initiation time, UTC format, example: 2025-07-02T15:04:05Z'
        server_name:
          type: string
          description: 'Client domain information, Fixed value: checkout.subotiz.com'
        payment_method_data:
          allOf:
            - $ref: '#/components/schemas/PaymentMethodData'
          description: >-
            Customer payment information, required for initial subscription
            payment when using `subscription` payment method
        summary:
          type: string
          description: >-
            If supported, the field, Transaction Summary, will be passed to the
            payment provider via its API.
             Currently, payments for amounts greater than zero via Subotiz Payments are supported only.
        refer_info:
          allOf:
            - $ref: '#/components/schemas/RequestReferInfo'
          description: Source information of the customer
    CreateTradeResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/CreateTradeResponse_Data'
      description: Query trade response by order_id
    CustomerData:
      type: object
      properties:
        email:
          type: string
          description: Customer email
        phone:
          type: string
          description: Customer phone number
        name:
          type: string
          description: Customer name
        address:
          type: string
          description: Customer detailed address
    PaymentMethodData:
      type: object
      properties:
        type:
          type: string
          description: |-
            Payment method type:
            - card: Card payment
        card:
          allOf:
            - $ref: '#/components/schemas/PaymentMethodDataCard'
          description: Bank card information, required when `type` is card.
    RequestReferInfo:
      type: object
      properties:
        source_ip:
          type: string
          description: The customer's IP address
        source_user_agent:
          type: string
          description: The customer's user agent
    CreateTradeResponse_Data:
      type: object
      properties:
        trade_id:
          type: string
          description: Trade ID
        access_no:
          type: string
          description: Third-party access number
        merchant_id:
          type: string
          description: Merchant ID
        amount:
          type: string
          description: Payment amount, truncated to two decimal places
        currency:
          type: string
          description: Currency
        customer_id:
          type: string
          description: Platform customer ID
        callback_url:
          type: string
          description: Webhook notification callback URL
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Passed-through metadata, key length ≤ 40 bytes, value length ≤ 500
            bytes, JSON encoded ≤ 1024 bytes
        last_payment_error:
          allOf:
            - $ref: '#/components/schemas/LastPaymentError'
          description: >-
            Last payment error information, if this field has a value, it
            indicates payment failure.
        next_action:
          allOf:
            - $ref: '#/components/schemas/NextAction'
          description: Next action
        order_id:
          type: string
          description: Third-party order number
        last_trans_id:
          type: string
          description: Order transaction ID
        paid_at:
          type: string
          description: Payment success time
        payment_mode:
          type: string
          description: >-
            Payment business mode:

            - subscription: Initial subscription payment, requires collecting
            customer payment information, pass `payment_method_data` field,
            returns `payment_token` for subsequent subscription renewals upon
            successful payment

            - recurring_payment: Subscription renewal payment, requires passing
            `payment_token` to complete payment, no need to collect user payment
            information
        payment_token:
          type: string
          description: >-
            Payment token returned for subscription payment, used for subsequent
            subscription renewals
        payment_method:
          type: string
          description: Payment method
        payment_channel:
          type: string
          description: Payment channel
        return_url:
          type: string
          description: >-
            Redirect page after payment channel accepts successfully in
            scenarios like 3DS redirect payment
        trade_status:
          type: string
          description: >-
            Payment 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: 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: 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.

            - succeeded: The payment has been confirmed successfully by the
            provider, and the funds have been credited.

            - 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:
          type: string
          description: Trade initiation time, time when client initiates the interface
        created_at:
          type: string
          description: Creation time
        refund_status:
          type: string
          description: >-
            Refund status:

            - no_refund: No refund

            - partially_refunded: A partial refund has been successfully issued,
            and the refunded amount is less than the total trade order value.

            - refunded: The full amount of the trade order has been successfully
            refunded.
        total_refunded_amount:
          type: string
          description: Refund amount, truncated to two decimal places
        session_id:
          type: string
          description: Session id
        session_url:
          type: string
          description: Session url
        refer_info:
          allOf:
            - $ref: '#/components/schemas/ReferInfo'
          description: Source information of the customer
        order_type:
          type: string
          description: >-
            Order types generated under different purchase or billing scenarios:

            - onetime_payment: The trade order is created for a one-time payment
            request.

            - subscription: The trade order is created for initiating a
            subscription payment request.

            - recurring_payment: The trade order is created by the Subotiz
            subscription renewal service.

            - token_payment: The trade order is created when the merchant
            charges a customer using an existing subscription contract token.
        tax_amount:
          type: string
          description: Tax amount
      description: Query trade response by order_id
    PaymentMethodDataCard:
      type: object
      properties:
        number:
          type: string
          description: 'Card number, example: 4761739012345611'
        exp_month:
          type: string
          description: 'Expiration month, example: 11'
        exp_year:
          type: string
          description: 'Expiration year, example: 2025'
        secure_code:
          type: string
          description: Security code (cvv/cvc)
        first_name:
          type: string
          description: Cardholder first name
        last_name:
          type: string
          description: Cardholder last name
    LastPaymentError:
      type: object
      properties:
        code:
          type: string
          description: System returned transaction return code
        message:
          type: string
          description: System returned transaction return description
    NextAction:
      type: object
      properties:
        type:
          type: string
          description: |-
            Type of next action required by client:
            - redirect: Redirect
        redirect:
          allOf:
            - $ref: '#/components/schemas/NextActionRedirect'
          description: Redirect information
        client:
          allOf:
            - $ref: '#/components/schemas/NextActionClient'
          description: Client operation information
      description: NextAction
    ReferInfo:
      type: object
      properties:
        country_code:
          type: string
          description: The country code of the client (ISO 2 format)
        ip:
          type: string
          description: The customer's IP address
        device:
          type: string
          description: |-
            The type of the customer's equipment
             - pc: Refers to the types of personal computer devices including desktops and laptops.
             - mobile: Refers to portable device types that have wireless connection capabilities and include smart phones and tablets.
        user_agent:
          type: string
          description: The customer's user agent
      description: ReferInfo
    NextActionRedirect:
      type: object
      properties:
        url:
          type: string
          description: Redirect URL
    NextActionClient:
      type: object
      properties:
        confirm_url:
          type: string
          description: Confirm payment URL
        apple_pay_session:
          type: string
          description: ApplePay session data for creation
  securitySchemes:
    sec0:
      type: http
      description: >-
        Bearer API Key authentication. Format: Authorization: Bearer
        {your_api_key}
      scheme: bearer

````