{"openapi":"3.0.3","info":{"title":"WhalePay Merchant Payment API","version":"1.0.0","description":"TRC20/BEP20 USDT merchant server API. Sign each request using WP-Key-ID, WP-Timestamp, WP-Nonce and WP-Signature. Exact raw body and stable Idempotency-Key for creation retries. No browser session or administrative endpoints. This document describes the runtime contract, not a live-service acceptance certificate."},"servers":[{"url":"https://whalepay.bizpalx.com"}],"paths":{"/v1/whoami":{"get":{"summary":"Authenticated tenant and project","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Whoami"}}}},"default":{"description":"Error; 400 input, 401 auth, 403 permission/CSRF, 404 scoped missing, 409 conflict, 410 checkout expiry, 413 size, 422 policy, 429 rate, 500 internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"WP-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Nonce","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/orders":{"post":{"summary":"Create a fixed or deferred-network USDT order","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Idempotent replay; returns original creation response even if current order changed. After encrypted response expiry, returns order_id and checkout_recovery_required=true.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreatedOrder"},{"type":"object","additionalProperties":false,"properties":{"order_id":{"type":"string"},"checkout_recovery_required":{"type":"boolean","enum":[true]}},"required":["order_id","checkout_recovery_required"]}]}}}},"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedOrder"}}}},"default":{"description":"Error; 400 input, 401 auth, 403 permission/CSRF, 404 scoped missing, 409 conflict, 410 checkout expiry, 413 size, 422 policy, 429 rate, 500 internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Nonce","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}}},"get":{"summary":"List project orders with keyset cursor","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"default":{"description":"Error; 400 input, 401 auth, 403 permission/CSRF, 404 scoped missing, 409 conflict, 410 checkout expiry, 413 size, 422 policy, 429 rate, 500 internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string"}},{"name":"merchant_order_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"WP-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Nonce","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/orders/{orderId}":{"get":{"summary":"Current project order","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"default":{"description":"Error; 400 input, 401 auth, 403 permission/CSRF, 404 scoped missing, 409 conflict, 410 checkout expiry, 413 size, 422 policy, 429 rate, 500 internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}},{"name":"WP-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Nonce","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/orders/{orderId}/cancel":{"post":{"summary":"Cancel pending or awaiting order before its deadline, releasing reservations once","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"default":{"description":"Error; 400 input, 401 auth, 403 permission/CSRF, 404 scoped missing, 409 conflict, 410 checkout expiry, 413 size, 422 policy, 429 rate, 500 internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Nonce","in":"header","required":true,"schema":{"type":"string"}},{"name":"WP-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"WP-Key-ID"}},"schemas":{"Whoami":{"type":"object","additionalProperties":false,"properties":{"tenant_id":{"type":"string"},"project_id":{"type":"string"},"api_key_id":{"type":"string"}},"required":["tenant_id","project_id","api_key_id"]},"Error":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]},"CreatedOrder":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"checkout_token":{"type":"string"},"checkout_url":{"type":"string","description":"Hosted checkout URL returned by the service. Treat the token as confidential; do not construct or replace the URL."}}}]},"Order":{"type":"object","properties":{"order_id":{"type":"string"},"merchant_order_id":{"type":"string"},"tenant_id":{"type":"string"},"project_id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"network":{"type":"string","nullable":true},"pay_address":{"type":"string","nullable":true},"asset_identifier":{"type":"string","nullable":true},"payable_atomic":{"type":"string","nullable":true},"payable_amount":{"type":"string","nullable":true},"fingerprint_amount":{"type":"string","nullable":true},"status":{"type":"string","enum":["awaiting_payment","pending","confirming","paid","expired","canceled"]},"decimals":{"type":"integer","enum":[6,18],"nullable":true},"required_confirmations":{"type":"integer","nullable":true},"instruction_revision":{"type":"integer","minimum":0,"description":"Zero before first selection."},"expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time","nullable":true},"paid_source":{"type":"string","nullable":true},"is_test_order":{"type":"boolean","enum":[false]},"exclude_from_metrics":{"type":"boolean","enum":[false]},"allowed_networks":{"type":"array","items":{"type":"string","enum":["TRC20","BEP20"]},"minItems":1,"maxItems":2,"uniqueItems":true,"description":"Defaults to selected network, or active project/plan network intersection when network is omitted. Explicit unavailable networks are rejected."},"selection_deadline":{"type":"string","format":"date-time"},"settled_atomic":{"type":"string"},"tx_hash":{"type":"string"},"event_index":{"type":"integer"},"confirmations":{"type":"integer"},"block_height":{"type":"string"},"block_hash":{"type":"string"},"block_time":{"type":"string","format":"date-time","nullable":true},"payment_risk":{"type":"string","enum":["clear","review_required"],"description":"Current committed scanner evidence; review_required requires investigation before fulfillment. A recorded paid reorg never clears automatically."}},"description":"A paid chain receipt preserves original evidence. Query payment_risk before fulfillment and process separate reorg events. Risk never clears automatically after a recorded paid reorg."},"CreateOrder":{"type":"object","additionalProperties":false,"properties":{"merchant_order_id":{"type":"string","minLength":1,"maxLength":128},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","description":"Strictly positive; string, never floating point."},"currency":{"type":"string","enum":["USDT"]},"network":{"type":"string","enum":["TRC20","BEP20"]},"allowed_networks":{"type":"array","items":{"type":"string","enum":["TRC20","BEP20"]},"minItems":1,"maxItems":2,"uniqueItems":true,"description":"Defaults to selected network, or active project/plan network intersection when network is omitted. Explicit unavailable networks are rejected."}},"required":["merchant_order_id","amount","currency"]},"OrderList":{"type":"object","additionalProperties":false,"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":"string","nullable":true}},"required":["orders","next_cursor"]}}}}