{"openapi":"3.1.0","info":{"title":"TomanPay Agent API","description":"Payment API for agents. Authenticate with `Authorization: Bearer <api key>`. Full guide (Persian): https://docs.tomanpay.online/","version":"1.0"},"paths":{"/v1/payments/request":{"post":{"tags":["payments"],"summary":"Request Payment","description":"Errors are returned with HTTP 200 as `{\"status\": \"error\", \"error_code\": \"..\", \"error_message\": \"..\"}`.","operationId":"request_payment_v1_payments_request_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/payments/inquiry":{"post":{"tags":["payments"],"summary":"Inquiry","description":"Errors are returned with HTTP 200 as `{\"status\": \"error\", \"error_code\": \"..\", \"error_message\": \"..\"}`.","operationId":"inquiry_v1_payments_inquiry_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentInquiryIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentInquiryOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PaymentInquiryIn":{"properties":{"payment_id":{"type":"string","format":"uuid","title":"Payment Id"}},"type":"object","required":["payment_id"],"title":"PaymentInquiryIn"},"PaymentInquiryOut":{"properties":{"status":{"type":"string","const":"success","title":"Status","default":"success"},"payment_id":{"type":"string","format":"uuid","title":"Payment Id"},"payment_status":{"type":"string","enum":["pending","paid","canceled","failed","expired"],"title":"Payment Status"},"amount":{"type":"integer","title":"Amount"},"paid_amount":{"type":"integer","title":"Paid Amount"},"customer_fee":{"type":"integer","title":"Customer Fee"},"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id"},"tracking_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking Number"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"paid_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid At"}},"type":"object","required":["payment_id","payment_status","amount","paid_amount","customer_fee","order_id","tracking_number","created_at","paid_at"],"title":"PaymentInquiryOut"},"PaymentRequestIn":{"properties":{"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Amount in toman"},"callback_url":{"type":"string","maxLength":2000,"title":"Callback Url","description":"http(s) URL the payer is redirected to (signed)"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description"},"order_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Order Id","description":"Your own order id"},"customer_fee_percent":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Customer Fee Percent","description":"Part of the commission (0-100 %) added to what the customer pays. Omit to use your default from the bot settings."}},"type":"object","required":["amount","callback_url"],"title":"PaymentRequestIn"},"PaymentRequestOut":{"properties":{"status":{"type":"string","const":"success","title":"Status","default":"success"},"payment_id":{"type":"string","format":"uuid","title":"Payment Id"},"payment_url":{"type":"string","title":"Payment Url"},"amount":{"type":"integer","title":"Amount","description":"Your order amount (as requested)"},"paid_amount":{"type":"integer","title":"Paid Amount","description":"What the customer pays: amount + customer_fee"},"customer_fee":{"type":"integer","title":"Customer Fee","description":"Part of the commission paid by the customer"}},"type":"object","required":["payment_id","payment_url","amount","paid_amount","customer_fee"],"title":"PaymentRequestOut"},"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":{"HTTPBearer":{"type":"http","description":"Agent API key: `Bearer tp_...`","scheme":"bearer"}}}}