{"openapi":"3.1.0","info":{"title":"IndieVouch API","description":"Signed REST API for creating and managing UPI orders. See https://indievouch.in/docs for the full authentication, webhook and versioning walkthrough.","version":"1.0.0"},"paths":{"/api/v1/merchant/order/create":{"post":{"tags":["api"],"summary":"Create an order","description":"Create a UPI order against one of your active payment nodes.\n\nThe request must be signed: HMAC-SHA256 of `amount:order_id:timestamp` keyed\nwith your API secret, in the `signature` field. `timestamp` must be within\n`SIGNATURE_WINDOW` (500s) of the server's clock. `order_id` must be unique per\nmerchant -- a repeat returns 409 rather than creating a duplicate order.\n\nFor `type=api_link`, redirect the customer to `pay_url`. For `type=api`, the\nresponse also carries `upi_uri` so you can render your own UPI intent/QR\ninstead.","operationId":"createOrder","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIn"}}}},"responses":{"201":{"description":"The created order, including a upi_uri for type=api","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/orders":{"get":{"tags":["api"],"summary":"List orders","description":"List your orders, newest first. Optionally filter by `status` (initiated,\nsubmitted, completed, flagged, failed, expired, refunded) or `source` (link,\nbutton, shop, api, api_link). `limit` is capped at 200.","operationId":"listOrders","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Orders newest-first, optionally filtered","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/order/{trx_id}":{"get":{"tags":["api"],"summary":"Get an order","description":"Fetch a single order by its `trx_id` (the `trx_id` returned from create) or by\nyour own `order_id` -- either lookup works so you don't have to store our id.","operationId":"getOrder","parameters":[{"name":"trx_id","in":"path","required":true,"schema":{"type":"string","title":"Trx Id"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"The order, by trx_id or your own order_id","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/order/{trx_id}/utr":{"post":{"tags":["api"],"summary":"Record a customer's UTR against an order","description":"Attach the UPI transaction reference a customer reports for an order --\nuseful when you're collecting the reference yourself rather than relying on\nautomatic SMS reconciliation.","operationId":"submitOrderUtr","parameters":[{"name":"trx_id","in":"path","required":true,"schema":{"type":"string","title":"Trx Id"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtrIn"}}}},"responses":{"200":{"description":"The order after recording the reference","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/order/{trx_id}/settle":{"post":{"tags":["api"],"summary":"Force an order to completed or failed","description":"Force an order to `completed` or `failed` directly, bypassing SMS-based\nreconciliation -- fires the same webhook event a normal settlement would.","operationId":"settleOrder","parameters":[{"name":"trx_id","in":"path","required":true,"schema":{"type":"string","title":"Trx Id"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettleIn"}}}},"responses":{"200":{"description":"The order after settling","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/nodes":{"get":{"tags":["api"],"summary":"List your payment nodes","description":"List the UPI payment nodes (VPAs) registered to your account -- the `vpa`\nvalues you can pass to `create_order`.","operationId":"listNodes","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Your active and inactive UPI payment nodes","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/merchant/node-entries":{"get":{"tags":["api"],"summary":"List observed bank credits","description":"List the raw bank-credit entries your device or Web Verify has reported,\nwhether or not each one has been linked to an order yet. `limit` is capped at\n200.","operationId":"listNodeEntries","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"linked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Linked"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Credits your device or Web Verify has reported","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OrderIn":{"properties":{"type":{"type":"string","title":"Type","description":"api | api_link","default":"api"},"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount"},"vpa":{"type":"string","title":"Vpa","description":"Must match one of your active payment node VPAs"},"customer_name":{"type":"string","title":"Customer Name"},"customer_email":{"type":"string","title":"Customer Email"},"customer_mobile":{"type":"string","title":"Customer Mobile","default":""},"description":{"type":"string","title":"Description"},"order_id":{"type":"string","title":"Order Id","description":"Your unique order reference"},"timestamp":{"type":"string","title":"Timestamp","description":"Unix timestamp in seconds"},"signature":{"type":"string","title":"Signature","description":"HMAC-SHA256 of amount:order_id:timestamp"},"redirect_url":{"type":"string","title":"Redirect Url","default":""}},"type":"object","required":["amount","vpa","customer_name","customer_email","description","order_id","timestamp","signature"],"title":"OrderIn"},"SettleIn":{"properties":{"status":{"type":"string","title":"Status","description":"completed | failed"},"note":{"type":"string","title":"Note","description":"Optional free-text note recorded against the order","default":""}},"type":"object","required":["status"],"title":"SettleIn"},"UtrIn":{"properties":{"utr":{"type":"string","title":"Utr","description":"The 12-digit UPI transaction reference the customer reports"}},"type":"object","required":["utr"],"title":"UtrIn"},"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"}}},"tags":[{"name":"api","description":"The signed /api/v1 developer API."}]}