CreateTradeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/subotiz-com/json-schema/subotiz-com-create-trade-request-schema.json",
  "title": "CreateTradeRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/subotiz-com-openapi.yml#/components/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": "#/$defs/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:\n- onetime_payment: One-time payment, requires collecting customer payment information, pass `payment_method_data` field.\n- subscription: Initial subscription payment, requires collecting customer payment information, pass `payment_method_data` field, returns `payment_token` for subsequent subscription renewals upon successful payment\n- 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": "#/$defs/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.\n Currently, payments for amounts greater than zero via Subotiz Payments are supported only."
    },
    "refer_info": {
      "allOf": [
        {
          "$ref": "#/$defs/RequestReferInfo"
        }
      ],
      "description": "Source information of the customer"
    }
  },
  "$defs": {
    "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:\n- card: Card payment"
        },
        "card": {
          "allOf": [
            {
              "$ref": "#/$defs/PaymentMethodDataCard"
            }
          ],
          "description": "Bank card information, required when `type` is card."
        }
      }
    },
    "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"
        }
      }
    },
    "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"
        }
      }
    }
  }
}