{"openapi":"3.0.3","info":{"title":"FinDistro Corporate API","version":"1.0.0","description":"Server-to-server API for corporate / API clients.\n\nOne surface: `/api/corp/v1/*` — JSON in, JSON out, carrying both a machine-readable `error` string and a numeric `code`.\n\nAuthentication is an issued API token plus an IP allowlist. Account passwords and PINs are never accepted.\n\nEvery money endpoint is idempotent on YOUR OWN reference (`urid` on recharge, `request_id` elsewhere). Resending the same reference replays the original outcome rather than charging twice — always reuse it when retrying a request whose response you did not receive.\n\nCall `GET /api/corp/v1/services` to discover which services are live for you right now rather than hardcoding a list."},"servers":[{"url":"https://freedata.in"}],"security":[{"ApiToken":[]}],"components":{"securitySchemes":{"ApiToken":{"type":"apiKey","in":"header","name":"X-Api-Token","description":"Your issued API token. It may also be sent as a `Authorization: Bearer <token>`, or as `Authorization: Bearer <token>`. Calls are additionally restricted to your allowlisted IP addresses."}}},"tags":[{"name":"Core (v1)","description":"The modern surface for new integrations. JSON in, JSON out, machine-readable string errors alongside a numeric code support can trace."},{"name":"Recharge (v1)","description":"Mobile and DTH recharge. Money endpoints are POST; status is GET."},{"name":"Bill payments — BBPS (v1)","description":"Browse the biller directory, render the biller's input form from its customer_params schema, fetch the live bill, then pay. Billers whose fetch_requirement is MANDATORY must be fetched before payment."}],"paths":{"/api/corp/v1/services":{"get":{"tags":["Core (v1)"],"summary":"What you can call today","operationId":"get_api_corp_v1_services","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"success","code":200,"client":"Acme Pvt Ltd","services":[{"service":"recharge","name":"Mobile & DTH recharge","enabled":true,"ready":true,"note":null}]}}}}},"description":"Read this instead of hardcoding a service list.\n\nenabled means the endpoints exist. ready means a vendor is switched on right now — if it is false the calls still answer safely and nothing is charged."}},"/api/corp/v1/balance":{"get":{"tags":["Core (v1)"],"summary":"Your wallet balance","operationId":"get_api_corp_v1_balance","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"success","code":200,"balance":"5000.0000"}}}}}}},"/api/corp/v1/transactions":{"get":{"tags":["Core (v1)"],"summary":"Your transaction history, all services","operationId":"get_api_corp_v1_transactions","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"page":1,"page_size":20,"total":4,"transactions":[{"ref":"R2607…","request_id":"ABC123","service":"recharge","account":"9876543219","amount":"10.0000","status":"failed"}]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"},"description":"Default 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"string"},"description":"Default 20, maximum 100."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"success | pending | failed."},{"name":"service","in":"query","required":false,"schema":{"type":"string"},"description":"recharge | bbps | money_transfer | travel."},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"yyyy-mm-dd."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"yyyy-mm-dd."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search by account, our ref, or your reference."}]}},"/api/corp/v1/recharge":{"post":{"tags":["Recharge (v1)"],"summary":"Place a recharge","operationId":"post_api_corp_v1_recharge","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"success","code":200,"order_id":"R2607…","urid":"ABC123","operator_ref":"OP998877","amount":"100.0000","account":"9876543210","balance":"4900.0000","message":"Recharge successful."}}}}},"description":"MONEY ENDPOINT. Idempotent on your own reference — resending the same one replays the original outcome instead of charging twice.\n\nstatus is success | pending | failed. A rejected request returns status:\"rejected\" with an error string and the matching numeric code.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string","description":"Customer number or DTH subscriber id."},"operator":{"type":"string","description":"LIVE operator code (e.g. LIVJIO00003) or our catalog code (e.g. jio). A bare number is an operator id, never an operator code."},"amount":{"type":"string","description":"Face value in rupees."},"urid":{"type":"string","description":"Your unique reference (idempotency key), max 64 characters."},"circle":{"type":"string","description":"Circle/state hint."},"customer_name":{"type":"string","description":"For your own records."}},"required":["account","operator","amount","urid"]}}}}},"get":{"tags":["Recharge (v1)"],"summary":"Status by your own reference","operationId":"get_api_corp_v1_recharge","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"urid","in":"query","required":true,"schema":{"type":"string"},"description":"The reference you sent."}]}},"/api/corp/v1/recharge/{ref}":{"get":{"tags":["Recharge (v1)"],"summary":"Status by our order id","operationId":"get_api_corp_v1_recharge_ref","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"success","code":200,"order_id":"R2607…","urid":"ABC123","operator_ref":"OP998877","amount":"100.0000","account":"9876543210","refunded":false}}}}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"},"description":"Our reference for the transaction."}]}},"/api/corp/v1/operators":{"get":{"tags":["Recharge (v1)"],"summary":"Operator catalog with codes and limits","operationId":"get_api_corp_v1_operators","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/corp/v1/recharge/plans":{"get":{"tags":["Recharge (v1)"],"summary":"Tariff plans for an operator/circle","operationId":"get_api_corp_v1_recharge_plans","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"operator","in":"query","required":true,"schema":{"type":"string"},"description":"Operator code."},{"name":"circle","in":"query","required":false,"schema":{"type":"string"},"description":"Circle name."}]}},"/api/corp/v1/recharge/circle":{"get":{"tags":["Recharge (v1)"],"summary":"Operator and circle lookup for a number","operationId":"get_api_corp_v1_recharge_circle","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"mobile","in":"query","required":true,"schema":{"type":"string"},"description":"Customer number."}]}},"/api/corp/v1/bbps/categories":{"get":{"tags":["Bill payments — BBPS (v1)"],"summary":"Biller categories with counts","operationId":"get_api_corp_v1_bbps_categories","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/corp/v1/bbps/billers":{"get":{"tags":["Bill payments — BBPS (v1)"],"summary":"Paginated biller directory","operationId":"get_api_corp_v1_bbps_billers","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Exact category string from /bbps/categories."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Name search."},{"name":"page","in":"query","required":false,"schema":{"type":"string"},"description":"Default 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"string"},"description":"Default 50, max 100."}]}},"/api/corp/v1/bbps/billers/{id}":{"get":{"tags":["Bill payments — BBPS (v1)"],"summary":"One biller WITH its input-form schema","operationId":"get_api_corp_v1_bbps_billers_id","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"description":"customer_params[].name must be echoed back verbatim on fetch and pay.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter."}]}},"/api/corp/v1/bbps/quote":{"get":{"tags":["Bill payments — BBPS (v1)"],"summary":"Price preview — no money, no vendor call","operationId":"get_api_corp_v1_bbps_quote","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"amount":"500.00","convenience_fee":"0.00","total":"500.00","charge":"500.00"}}}}},"parameters":[{"name":"biller_id","in":"query","required":true,"schema":{"type":"string"},"description":"Biller id."},{"name":"amount","in":"query","required":true,"schema":{"type":"string"},"description":"Bill amount in rupees."}]}},"/api/corp/v1/bbps/fetch":{"post":{"tags":["Bill payments — BBPS (v1)"],"summary":"Fetch the live bill (no money)","operationId":"post_api_corp_v1_bbps_fetch","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"description":"The returned fetch_ref binds to the bill you fetched and must be sent on pay.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller id."},"params":{"type":"string","description":"The biller's customer parameters, as a name→value object or a [{name,value}] list."},"customer_mobile":{"type":"string","description":"Customer contact number."}},"required":["biller_id","params"]}}}}}},"/api/corp/v1/bbps/pay":{"post":{"tags":["Bill payments — BBPS (v1)"],"summary":"Pay the bill","operationId":"post_api_corp_v1_bbps_pay","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"description":"MONEY ENDPOINT. Idempotent on your own reference — resending the same one replays the original outcome instead of charging twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller id."},"params":{"type":"string","description":"Same customer parameters used on fetch."},"amount":{"type":"string","description":"Amount in rupees."},"request_id":{"type":"string","description":"Your unique reference (idempotency key), max 64 characters."},"fetch_ref":{"type":"string","description":"Required for billers whose fetch_requirement is MANDATORY."}},"required":["biller_id","params","amount","request_id"]}}}}}},"/api/corp/v1/bbps/{ref}":{"get":{"tags":["Bill payments — BBPS (v1)"],"summary":"Status of one of your bill payments","operationId":"get_api_corp_v1_bbps_ref","responses":{"200":{"description":"Result. The outcome is `status` plus a numeric `code`.","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"},"description":"Our reference for the transaction."}]}}},"x-result-codes":{"101":"Invalid state code","102":"Invalid opcode value","103":"Invalid Amount","104":"Invalid user mobile number","105":"Invalid pin provided","106":"Invalid urid value","107":"Invalid login details","108":"Operator down time","111":"Transaction already running","112":"Insufficient balance","113":"Internal server error","115":"Duplicate recharge not allowed within 10 minutes","116":"Invalid order id","117":"Order id not found","120":"Recharge is pending","121":"Transaction on hold - a support review is in progress","122":"Recharge failed","123":"Server is busy","124":"Service is down","126":"Invalid data provided","127":"Max limit for each customer is only 100000 Rs","200":"SUCCESS","201":"Recharge is pending","213":"Invalid Number","331":"Your account has been suspended, Please contact your administrator","351":"Recharge amount not in range","1144":"This operator service has been temporarily unavailable","2428":"IP Validation failed","2555":"Duplicate urid","2666":"Your account has been blocked for wrong credentials, please contact customer support"}}