{"openapi":"3.1.0","info":{"title":"OxyPay API","version":"1.0.0","description":"Create hosted bKash/Nagad/Rocket/Upay checkouts and read their status. Use oxp_test_ keys for sandbox payments and oxp_live_ keys for real ones. Keep keys on your server only."},"servers":[{"url":"https://oxypay.oxygentrade.xyz/api/public/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"oxp_live_sk_… or oxp_test_sk_…"}},"schemas":{"Payment":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string","example":"BDT"},"status":{"type":"string","enum":["pending","verifying","under_review","success","failed","expired","cancelled","refunded","partially_refunded"]},"verified":{"type":"boolean","description":"Only true after OxyPay has verified the money. Confirm orders only when status is success and verified is true."},"method":{"type":["string","null"],"enum":["bkash","nagad","rocket","upay",null]},"transaction_id":{"type":["string","null"]},"livemode":{"type":"boolean","description":"false for payments made with an oxp_test_ key (no real money)."},"checkout_url":{"type":"string","format":"uri"},"checkout_path":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"bearer":[]}],"paths":{"/payments":{"post":{"summary":"Create a payment","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100},"description":"Same key + same body within 24h returns the same payment."},{"name":"OxyPay-Timestamp","in":"header","required":false,"schema":{"type":"string","example":"1767225600"},"description":"Unix seconds. Needed when signing."},{"name":"OxyPay-Signature","in":"header","required":false,"schema":{"type":"string","example":"v1=5f2b…"},"description":"v1=HMAC-SHA256(signing_secret, `${timestamp}.${METHOD}.${path}.${rawBody}`) as hex. Required if the key has 'signed requests only' on."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","order_id"],"properties":{"amount":{"type":"number","minimum":1,"maximum":1000000},"order_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":{"type":"string","maxLength":120},"return_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Already existed for this order_id / Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string","example":"BDT"},"status":{"type":"string","enum":["pending","verifying","under_review","success","failed","expired","cancelled","refunded","partially_refunded"]},"verified":{"type":"boolean","description":"Only true after OxyPay has verified the money. Confirm orders only when status is success and verified is true."},"method":{"type":["string","null"],"enum":["bkash","nagad","rocket","upay",null]},"transaction_id":{"type":["string","null"]},"livemode":{"type":"boolean","description":"false for payments made with an oxp_test_ key (no real money)."},"checkout_url":{"type":"string","format":"uri"},"checkout_path":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string","example":"BDT"},"status":{"type":"string","enum":["pending","verifying","under_review","success","failed","expired","cancelled","refunded","partially_refunded"]},"verified":{"type":"boolean","description":"Only true after OxyPay has verified the money. Confirm orders only when status is success and verified is true."},"method":{"type":["string","null"],"enum":["bkash","nagad","rocket","upay",null]},"transaction_id":{"type":["string","null"]},"livemode":{"type":"boolean","description":"false for payments made with an oxp_test_ key (no real money)."},"checkout_url":{"type":"string","format":"uri"},"checkout_path":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"invalid_api_key, signature_required or invalid_signature","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"merchant_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"rate_limited (120 requests/minute per key). See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/payments/{id}":{"get":{"summary":"Get a payment by payment_id or order_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"OxyPay-Timestamp","in":"header","required":false,"schema":{"type":"string","example":"1767225600"},"description":"Unix seconds. Needed when signing."},{"name":"OxyPay-Signature","in":"header","required":false,"schema":{"type":"string","example":"v1=5f2b…"},"description":"v1=HMAC-SHA256(signing_secret, `${timestamp}.${METHOD}.${path}.${rawBody}`) as hex. Required if the key has 'signed requests only' on."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string","example":"BDT"},"status":{"type":"string","enum":["pending","verifying","under_review","success","failed","expired","cancelled","refunded","partially_refunded"]},"verified":{"type":"boolean","description":"Only true after OxyPay has verified the money. Confirm orders only when status is success and verified is true."},"method":{"type":["string","null"],"enum":["bkash","nagad","rocket","upay",null]},"transaction_id":{"type":["string","null"]},"livemode":{"type":"boolean","description":"false for payments made with an oxp_test_ key (no real money)."},"checkout_url":{"type":"string","format":"uri"},"checkout_path":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"invalid_api_key, signature_required or invalid_signature","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"merchant_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"rate_limited (120 requests/minute per key). See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}},"webhooks":{"paymentEvent":{"post":{"summary":"payment.under_review, payment.succeeded, payment.failed, payment.expired, payment.refunded, payment.partially_refunded, payment.cancelled, webhook.test","parameters":[{"name":"OxyPay-Event-Id","in":"header","schema":{"type":"string"}},{"name":"OxyPay-Event-Type","in":"header","schema":{"type":"string"}},{"name":"OxyPay-Timestamp","in":"header","schema":{"type":"string"}},{"name":"OxyPay-Signature","in":"header","schema":{"type":"string"},"description":"v1=HMAC-SHA256(webhook_secret, `${timestamp}.${rawBody}`) as hex"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"created_at":{"type":"string"},"livemode":{"type":"boolean"},"data":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string","example":"BDT"},"status":{"type":"string","enum":["pending","verifying","under_review","success","failed","expired","cancelled","refunded","partially_refunded"]},"verified":{"type":"boolean","description":"Only true after OxyPay has verified the money. Confirm orders only when status is success and verified is true."},"method":{"type":["string","null"],"enum":["bkash","nagad","rocket","upay",null]},"transaction_id":{"type":["string","null"]},"livemode":{"type":"boolean","description":"false for payments made with an oxp_test_ key (no real money)."},"checkout_url":{"type":"string","format":"uri"},"checkout_path":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"responses":{"200":{"description":"Return any 2xx within 10 seconds. Anything else is retried (5m, 15m, 30m, 1h, 3h, 6h, 12h)."}}}}}}