{
  "openapi": "3.1.0",
  "info": {
    "title": "ATO Merchant API",
    "version": "1.0.0",
    "description": "Escrow for cross-border B2B: hold the buyer's card payment at checkout, report the waybill, and funds release in three parts as the shipment departs, clears customs and is delivered (the delivery tranche after the buyer's acceptance window). Amounts are integers in minor units (USD cents). Guide: https://ato.aijdt.com/developers/"
  },
  "servers": [
    {
      "url": "https://ato.aijdt.com",
      "description": "Sandbox while in pilot"
    }
  ],
  "paths": {
    "/v1/merchant/orders": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Create Order",
        "description": "Hold funds on the buyer's saved card at checkout. Idempotent by merchant_order_no: the same number returns the same result; the same number with a different amount returns 409.",
        "operationId": "create_order_v1_merchant_orders_post",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMerchantOrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "List Orders",
        "description": "Reconciliation list of your orders, newest first. Filter by since / until (ISO-8601) and status; limit up to 500.",
        "operationId": "list_orders_v1_merchant_orders_get",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Since"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Until"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Status"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "title": "Limit"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchant/orders/{merchant_order_no}": {
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "Get Order",
        "operationId": "get_order_v1_merchant_orders__merchant_order_no__get",
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Merchant Order No"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Order status, each released tranche and settlement receipts."
      }
    },
    "/v1/merchant/orders/{merchant_order_no}/cancel": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Cancel Order",
        "operationId": "cancel_order_v1_merchant_orders__merchant_order_no__cancel_post",
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Merchant Order No"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/CancelMerchantOrderRequest"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Body"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Before shipping only. Releases or refunds the full amount to the buyer's card. After shipping, open a dispute instead."
      }
    },
    "/v1/merchant/orders/{merchant_order_no}/shipment": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Attach Shipment",
        "operationId": "attach_shipment_v1_merchant_orders__merchant_order_no__shipment_post",
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Merchant Order No"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachShipmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Report the carrier and waybill number after shipping. ATO subscribes to tracking and releases funds at departure, customs clearance and delivery. Idempotent per waybill number."
      }
    },
    "/v1/merchant/orders/{merchant_order_no}/dispute": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Open Dispute",
        "description": "After shipping only. Freezes the part not yet released; ATO reviews. If approved the unreleased part is refunded to the buyer's card; released parts are not clawed back.",
        "operationId": "open_dispute_v1_merchant_orders__merchant_order_no__dispute_post",
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Merchant Order No"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OpenDisputeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchant/orders/{merchant_order_no}/confirm-receipt": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Confirm Receipt",
        "description": "After delivery. The final tranche (default 40%) is held for an acceptance window (default 5 days, status `delivered`). Call this when the buyer confirms the goods are fine to release it immediately; otherwise it releases automatically when the window ends. 409 not_delivered before delivery, 409 order_disputed while a dispute is open. Idempotent.",
        "operationId": "confirm_receipt_v1_merchant_orders__merchant_order_no__confirm_receipt_post",
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Merchant Order No"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchant/bind-sessions": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Create Bind Session",
        "operationId": "create_bind_session_v1_merchant_bind_sessions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBindSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Start a card-saving session for one of your buyers. Redirect the buyer to the returned bind_url; they return to your return_url with ato_status and binding_id."
      }
    },
    "/v1/merchant/bind-sessions/{sid}": {
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "Get Bind Session",
        "operationId": "get_bind_session_v1_merchant_bind_sessions__sid__get",
        "parameters": [
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Confirm the session result server-side. Treat the card as saved only when status is bound."
      }
    },
    "/v1/merchant/bind/{sid}/start": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Bind Start",
        "operationId": "bind_start_v1_merchant_bind__sid__start_post",
        "parameters": [
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Called by the ATO-hosted card page in the buyer's browser. Merchants do not call it."
      }
    },
    "/v1/merchant/bind/{sid}/confirm": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Bind Confirm",
        "operationId": "bind_confirm_v1_merchant_bind__sid__confirm_post",
        "parameters": [
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BindConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Called by the ATO-hosted card page in the buyer's browser. Merchants do not call it."
      }
    },
    "/v1/merchant/bind/{sid}/cancel": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Bind Cancel",
        "operationId": "bind_cancel_v1_merchant_bind__sid__cancel_post",
        "parameters": [
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Called by the ATO-hosted card page in the buyer's browser. Merchants do not call it."
      }
    }
  },
  "components": {
    "schemas": {
      "AttachShipmentRequest": {
        "properties": {
          "carrier_code": {
            "type": "string",
            "title": "Carrier Code",
            "default": "17track"
          },
          "tracking_no": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "title": "Tracking No"
          },
          "jd_order_no": {
            "type": "string",
            "title": "Jd Order No",
            "default": ""
          }
        },
        "type": "object",
        "required": [
          "tracking_no"
        ],
        "title": "AttachShipmentRequest"
      },
      "BindConfirmRequest": {
        "properties": {
          "payload": {
            "additionalProperties": true,
            "type": "object",
            "title": "Payload"
          }
        },
        "type": "object",
        "title": "BindConfirmRequest"
      },
      "CancelMerchantOrderRequest": {
        "properties": {
          "reason": {
            "type": "string",
            "title": "Reason",
            "default": "merchant_cancelled"
          }
        },
        "type": "object",
        "title": "CancelMerchantOrderRequest"
      },
      "CreateBindSessionRequest": {
        "properties": {
          "buyer_ref": {
            "type": "string",
            "maxLength": 128,
            "minLength": 1,
            "title": "Buyer Ref"
          },
          "return_url": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 8,
            "title": "Return Url"
          },
          "buyer_email": {
            "type": "string",
            "title": "Buyer Email",
            "default": ""
          },
          "locale": {
            "type": "string",
            "title": "Locale",
            "default": "en-US"
          }
        },
        "type": "object",
        "required": [
          "buyer_ref",
          "return_url"
        ],
        "title": "CreateBindSessionRequest"
      },
      "CreateMerchantOrderRequest": {
        "properties": {
          "merchant_order_no": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "title": "Merchant Order No"
          },
          "amount_minor": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Amount Minor"
          },
          "currency": {
            "type": "string",
            "title": "Currency",
            "default": "USD"
          },
          "binding_id": {
            "type": "string",
            "title": "Binding Id",
            "default": ""
          },
          "buyer_ref": {
            "type": "string",
            "title": "Buyer Ref",
            "default": ""
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/MerchantOrderItem"
            },
            "type": "array",
            "title": "Items"
          },
          "shipping_address": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShippingAddress"
              },
              {
                "type": "null"
              }
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object",
            "title": "Metadata"
          }
        },
        "type": "object",
        "required": [
          "merchant_order_no",
          "amount_minor"
        ],
        "title": "CreateMerchantOrderRequest"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "MerchantOrderItem": {
        "properties": {
          "sku": {
            "type": "string",
            "title": "Sku",
            "default": ""
          },
          "name": {
            "type": "string",
            "title": "Name",
            "default": ""
          },
          "qty": {
            "type": "integer",
            "title": "Qty",
            "default": 1
          },
          "unit_price_minor": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Unit Price Minor"
          }
        },
        "type": "object",
        "title": "MerchantOrderItem"
      },
      "OpenDisputeRequest": {
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 500,
            "minLength": 1,
            "title": "Reason"
          },
          "evidence_urls": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Evidence Urls"
          }
        },
        "type": "object",
        "required": [
          "reason"
        ],
        "title": "OpenDisputeRequest"
      },
      "ShippingAddress": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "phone": {
            "type": "string",
            "title": "Phone"
          },
          "address1": {
            "type": "string",
            "title": "Address1"
          },
          "address2": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Address2"
          },
          "city": {
            "type": "string",
            "title": "City"
          },
          "state": {
            "type": "string",
            "title": "State"
          },
          "zip": {
            "type": "string",
            "title": "Zip"
          },
          "country": {
            "type": "string",
            "title": "Country",
            "default": "US"
          }
        },
        "type": "object",
        "required": [
          "name",
          "phone",
          "address1",
          "city",
          "state",
          "zip"
        ],
        "title": "ShippingAddress",
        "description": "对话/API 侧收集的收货地址。jdl_* 方法输出 JDL UAT 接受的格式\n（州全称 / 1-XXXXXXXXXX 电话 / ZIP+4）——格式陷阱集中在这里归一，\n不指望上游 LLM 或调用方给对格式。"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    },
    "securitySchemes": {
      "merchantKey": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "merchantKey": []
    }
  ]
}