{"openapi":"3.1.0","info":{"title":"ChainPay API","version":"1.0.0","description":"Create and monitor cryptocurrency payment orders. API keys are sent as Bearer tokens."},"servers":[{"url":"https://chainpay.pro/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_ or sk_test_ API key"}},"schemas":{"CreateOrder":{"type":"object","required":["amount","currency","chain"],"properties":{"amount":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string","pattern":"^[0-9]+(?:\\.[0-9]{1,6})?$"}]},"currency":{"type":"string","enum":["USDT","ETH","BTC","SOL"]},"chain":{"type":"string","enum":["trc20","erc20","btc","sol"]},"externalId":{"type":"string","maxLength":128},"appId":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}},"Order":{"type":"object","properties":{"orderId":{"type":"string"},"payAddress":{"type":"string"},"cryptoAmount":{"type":"string"},"currency":{"type":"string"},"chain":{"type":"string"},"status":{"type":"string","enum":["pending","confirming","completed","expired","failed"]},"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"fulfillmentStatus":{"type":"string","enum":["not_required","awaiting_receipt","completed","escalated"]}}},"FulfillmentReceipt":{"type":"object","required":["event","receiptId","orderId","externalId","fulfilledAt","issuedAt","creditedAmount"],"properties":{"event":{"type":"string","const":"fulfillment.completed"},"receiptId":{"type":"string","maxLength":160},"orderId":{"type":"string","maxLength":160},"externalId":{"type":"string","maxLength":160},"fulfilledAt":{"type":"string","format":"date-time"},"issuedAt":{"type":"string","format":"date-time","description":"Fresh signing time; must be within the allowed clock-skew window."},"creditedAmount":{"type":"string","pattern":"^[0-9]+(?:\\.[0-9]{1,8})?$"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/orders":{"post":{"operationId":"createOrder","summary":"Create a payment order","description":"Requires orders:write. Always send a unique Idempotency-Key (8-128 characters).","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"409":{"description":"Idempotency conflict"}}},"get":{"operationId":"listOrders","summary":"List payment orders","description":"Requires orders:read.","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Order list"}}}},"/orders/{id}":{"get":{"operationId":"getOrder","summary":"Get one payment order","description":"Requires orders:read for the merchant response.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"},"404":{"description":"Not found"}}}},"/rates":{"get":{"operationId":"getRates","summary":"Get current public rates","security":[],"responses":{"200":{"description":"Rates"}}}},"/sandbox/simulate-payment":{"post":{"operationId":"simulateSandboxPayment","summary":"Simulate payment for a test order","description":"Only accepts sk_test_ keys.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string"}}}}}},"responses":{"200":{"description":"Simulated"}}}},"/webhooks/test":{"post":{"operationId":"sendTestWebhook","summary":"Send a test webhook","description":"Requires a live key and orders:write.","responses":{"200":{"description":"Sent"}}}},"/fulfillment-receipts":{"post":{"operationId":"submitFulfillmentReceipt","summary":"Confirm downstream business fulfillment","description":"Merchant-server callback for apps with receipt mode enabled. Sign the exact raw JSON body using HMAC-SHA256 and the app webhook secret. Agents must not synthesize receipts.","security":[],"parameters":[{"name":"X-ChainPay-Fulfillment-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentReceipt"}}}},"responses":{"200":{"description":"Receipt accepted or idempotently replayed"},"401":{"description":"Signature verification failed"},"409":{"description":"Receipt does not match the order state"}}}}}}