{"openapi":"3.1.0","info":{"title":"XiaPay Customer Integration API","version":"1.0.0","description":"Customer boundary only; no administrator/scanner APIs. Use the API base and environment assigned to your application. Payment and fulfilment are separate facts."},"servers":[{"url":"https://xiapay.ink"}],"security":[{"AppKey":[]}],"paths":{"/api/v1/orders":{"post":{"summary":"Create one order using an immutable business ID and idempotency key","responses":{"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"},"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}}},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["business_order_id","product_code","base_amount","asset_id","network"],"properties":{"business_order_id":{"type":"string","maxLength":128},"product_code":{"type":"string","maxLength":128},"base_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"asset_id":{"const":"tron-usdt"},"network":{"const":"tron"},"product_snapshot":{"type":"object"},"ttl_seconds":{"type":"integer","minimum":300,"maximum":86400,"default":1800}}}}}}},"get":{"summary":"Find one order by its business ID","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"}},"parameters":[{"in":"query","name":"business_order_id","required":true,"schema":{"type":"string"}}]}},"/api/v1/orders/{order_id}":{"get":{"summary":"Get one owned order; cross-application IDs return 404","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"},"404":{"description":"Order not found in this app"}},"parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"string"}}]}},"/api/v1/orders/{order_id}/fulfillment":{"post":{"summary":"Report business fulfilment without modifying the payment fact","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"}},"parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["processing","completed","failed"]},"detail":{"type":"string","maxLength":500}}}}}}}},"/api/v1/integration":{"get":{"summary":"Authenticate app/environment and record an API connectivity observation","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"}}}},"/api/v1/integration/acknowledgements":{"post":{"summary":"Record explicit client implementation declarations for the current configuration","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid API key"},"409":{"description":"Conflict / incomplete onboarding"},"422":{"description":"Invalid fields or pilot amount"},"503":{"description":"New orders closed or pilot limit reached"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configuration","environment","signature_verification","idempotent_fulfillment","query_recovery"],"properties":{"configuration":{"type":"string","minLength":64,"maxLength":64},"environment":{"enum":["live","sandbox"]},"signature_verification":{"const":true},"idempotent_fulfillment":{"const":true},"query_recovery":{"const":true}}}}}}}},"/api/v1/integration/kit.zip":{"get":{"summary":"Download generic integration assets; no customer credentials","security":[],"responses":{"200":{"description":"ZIP archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v1/integration/openapi.json":{"get":{"summary":"Customer-only API contract","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"AppKey":{"type":"http","scheme":"bearer","description":"Application server API key; never put it in frontend code."}},"schemas":{"Order":{"type":"object","properties":{"id":{"type":"string"},"business_order_id":{"type":"string"},"app_id":{"type":"string"},"environment":{"type":"string"},"product_code":{"type":"string"},"network":{"type":"string"},"asset_id":{"type":"string"},"contract":{"type":"string"},"address":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"payment_status":{"type":"string"},"fulfillment_status":{"type":"string"},"status_reason":{"type":"string"},"canonical_transfer_id":{"type":["string","null"]},"checkout_url":{"type":"string"},"base_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"quote_adjustment":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"pay_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"amount_units":{"type":"string","pattern":"^[0-9]+$"},"late_payment":{"type":"boolean"},"product_snapshot":{"type":"object"},"decimals":{"type":"integer","const":6}}},"PaymentSettled":{"type":"object","required":["event_id","type","payment_order_id","business_order_id","app_id","environment","payment_status","asset_id","network","canonical_transfer_id","tx_hash","occurred_at","base_amount","pay_amount","paid_amount","schema_version","log_index","late_payment"],"properties":{"event_id":{"type":"string"},"type":{"const":"payment.settled"},"payment_order_id":{"type":"string"},"business_order_id":{"type":"string"},"app_id":{"type":"string"},"environment":{"type":"string"},"payment_status":{"const":"settled"},"asset_id":{"type":"string"},"network":{"type":"string"},"canonical_transfer_id":{"type":"string"},"tx_hash":{"type":"string"},"occurred_at":{"type":"string"},"base_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"pay_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"paid_amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Decimal string; never a binary floating-point value."},"schema_version":{"const":1},"log_index":{"type":"integer","minimum":0},"late_payment":{"type":"boolean"}}},"IntegrationChallenge":{"type":"object","required":["schema_version","event_id","type","app_id","environment","challenge"],"properties":{"schema_version":{"const":1},"type":{"const":"integration.challenge"},"event_id":{"type":"string"},"app_id":{"type":"string"},"environment":{"enum":["live","sandbox"]},"challenge":{"type":"string","minLength":16,"maxLength":128}}}}},"webhooks":{"signedCustomerCallback":{"post":{"summary":"Signed payment event or non-financial integration challenge","security":[],"parameters":[{"in":"header","name":"X-XiaPay-Key-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-XiaPay-Timestamp","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-XiaPay-Event-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-XiaPay-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PaymentSettled"},{"$ref":"#/components/schemas/IntegrationChallenge"}]}}}},"responses":{"200":{"description":"Durably received payment event, or challenge echo. Not proof of business fulfilment."},"401":{"description":"Signature, timestamp or scope rejected"}}}}}}