{ "openapi": "3.1.0", "info": { "title": "KoviraPay Merchant & Reseller API", "version": "1.0", "description": "HTTP JSON API for merchant checkout. Server-side keys only. Live payment processing depends on independently verified routing and provider eligibility. Browser return URLs are not payment proof." }, "servers": [ { "url": "https://kovirapay.com", "description": "Production host; test mode selected via test API key" } ], "tags": [ { "name": "Merchant payments" }, { "name": "Reseller payments" }, { "name": "WooCommerce" } ], "components": { "securitySchemes": { "MerchantBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque kp_test_ or kp_live_ key" }, "ResellerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque kr_test_ or kr_live_ key; LIVE requires additional HMAC headers" } }, "schemas": { "PaymentCreate": { "type": "object", "required": [ "order_id", "idempotency_key", "amount" ], "properties": { "order_id": { "type": "string", "maxLength": 150, "example": "ORDER-1042" }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9._:-]+$", "example": "shop-order-1042-v1" }, "amount": { "type": "string", "description": "Two-decimal positive invoice amount", "example": "49.99" }, "currency": { "type": "string", "default": "USD", "example": "EUR" }, "checkout_mode": { "type": "string", "enum": [ "hosted", "direct" ], "default": "hosted" }, "payment_method": { "type": "string", "enum": [ "credit_card", "paypal", "ideal", "cash_app", "crypto", "venmo", "revolut", "klarna", "upi_imps", "interac" ] }, "customer_email": { "type": "string", "format": "email" }, "return_url": { "type": "string", "format": "uri", "description": "Optional HTTPS URL under a verified merchant shop domain" } } }, "Payment": { "type": "object", "properties": { "payment_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "order_id": { "type": "string" }, "status": { "type": "string" }, "settlement_status": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "usd_amount": { "type": "string" }, "payment_method": { "type": [ "string", "null" ] }, "test_mode": { "type": "boolean" }, "checkout_url": { "type": "string", "format": "uri" } }, "required": [ "payment_id", "order_id", "status", "settlement_status", "amount", "currency", "usd_amount", "test_mode", "checkout_url" ] }, "StartRequest": { "type": "object", "required": [ "payment_id", "payment_method" ], "properties": { "payment_id": { "type": "string" }, "payment_method": { "type": "string" }, "provider_id": { "type": "string", "description": "Optional; only if authorized by routing policy" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "ResellerCreate": { "type": "object", "required": [ "merchant_id", "client_ref", "order_id", "amount", "currency" ], "properties": { "merchant_id": { "type": "integer" }, "client_ref": { "type": "string" }, "order_id": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "payment_method": { "type": "string" }, "checkout_mode": { "type": "string", "enum": [ "hosted", "direct" ] }, "customer_email": { "type": "string", "format": "email" }, "return_url": { "type": "string", "format": "uri" } } } } }, "paths": { "/api/v1/payments": { "post": { "tags": [ "Merchant payments" ], "summary": "Create a checkout session (idempotent)", "security": [ { "MerchantBearer": [] } ], "responses": { "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreate" } } } }, "description": "Only the merchant backend may send API key credentials. First successful creation uses HTTP 201; replay returns the existing payment. The payment is not considered paid on browser return." } }, "/api/v1/methods": { "get": { "tags": [ "Merchant payments" ], "summary": "View currently configured and eligible payment methods", "security": [ { "MerchantBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "amount", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } } ] } }, "/api/v1/payments/start": { "post": { "tags": [ "Merchant payments" ], "summary": "Start a direct-mode payment and receive redirect_url", "security": [ { "MerchantBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string" }, "redirect_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRequest" } } } } } }, "/api/v1/payments/{payment_id}": { "get": { "tags": [ "Merchant payments" ], "summary": "Read payment state; fulfillment requires live completed + confirmed", "security": [ { "MerchantBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/reseller/invitations": { "post": { "tags": [ "Reseller payments" ], "summary": "Invite merchant to join reseller account", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "business_name", "client_ref" ], "properties": { "email": { "type": "string", "format": "email" }, "business_name": { "type": "string" }, "client_ref": { "type": "string" } } } } } } } }, "/api/v1/reseller/merchants": { "get": { "tags": [ "Reseller payments" ], "summary": "List delegated merchants and authorization status", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reseller/payments": { "get": { "tags": [ "Reseller payments" ], "summary": "List payments created by this reseller for one authorized merchant", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "merchant_id", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Reseller payments" ], "summary": "Create delegated checkout after merchant authorization", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResellerCreate" } } } } } }, "/api/v1/reseller/payments/start": { "post": { "tags": [ "Reseller payments" ], "summary": "Start a reseller direct payment", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRequest" } } } } } }, "/api/v1/reseller/payments/{payment_id}": { "get": { "tags": [ "Reseller payments" ], "summary": "Get status for a payment created by the calling reseller", "security": [ { "ResellerBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/connect/exchange": { "post": { "tags": [ "WooCommerce" ], "summary": "Exchange a one-time five-minute code after proving shop control", "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "site_url", "challenge", "proof" ], "properties": { "code": { "type": "string" }, "site_url": { "type": "string", "format": "uri" }, "challenge": { "type": "string" }, "proof": { "type": "string" } } } } } }, "description": "Used by the official WooCommerce plugin; this endpoint requires shop ownership proof and a single-use code, not the merchant Bearer key." } }, "/api/v1/woocommerce/releases/latest": { "get": { "tags": [ "WooCommerce" ], "summary": "Latest published WooCommerce plugin version", "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public read-only plugin release metadata." } } }, "x-kovira-notes": { "webhook": "Signed merchant events use v1=HMAC_SHA256(timestamp.event_id.raw_body) with each endpoint secret. Verify timestamp window, event dedup, order fields and settlement_status=confirmed.", "liveResellerHmac": "Live reseller requests include X-Kovira-Timestamp, X-Kovira-Nonce and X-Kovira-Signature; see /api-docs.", "versionPolicy": "Reference corresponds to KoviraPay v0.24.1; runtime route approval and provider status may limit capabilities." } }