{"openapi":"3.1.0","info":{"title":"CigalPay Coins API","version":"1.0.0","description":"\n## Overview\n\nThe **Coins API** handles the pre-invoice flow and invoice charging for the CigalPay payment gateway.\n\n### Typical Flow\n\n1. **Create a pre-invoice** — merchant calls `POST /api/pre-invoice` with the fiat amount, currency, and callback URLs. Receives an encrypted `id` and a `chargeLink` to redirect the customer to.\n2. **Customer selects coin** — the pre-invoice client calls `POST /api/charge-invoice` once the customer picks a cryptocurrency. This creates a real payment on the backend and returns the payment address.\n3. **Poll payment status** — use the payment `id` returned by `/charge-invoice` to poll the primary backend's `/getPaymentStatus` endpoint.\n    ","contact":{"name":"CigalPay Support"}},"servers":[{"url":"https://coins-api.cigalpay.com","description":"Local dev"},{"url":"https://dcos.cigalpay.com","description":"Official documentation"}],"paths":{"/api/pre-invoice":{"post":{"summary":"Create a pre-invoice","operationId":"createPreInvoice","tags":["Pre-Invoice"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lang","currency","amount","accountId","description","ipn","callback","extraId"],"properties":{"lang":{"type":"string","example":"en","description":"UI language code (e.g. \"en\", \"fr\")"},"currency":{"type":"string","enum":["USD","EUR"],"example":"USD","description":"Fiat currency of the invoice"},"amount":{"type":"number","example":25,"description":"Fiat amount to charge"},"accountId":{"type":"string","example":"6643f2a1e4b0a1234567890a","description":"Merchant account ID (MongoDB ObjectId)"},"description":{"type":"string","example":"Order #1042","description":"Human-readable invoice description"},"ipn":{"type":"string","format":"uri","example":"https://merchant.com/ipn","description":"IPN callback URL called when payment status changes"},"callback":{"type":"string","format":"uri","example":"https://merchant.com/thank-you","description":"Redirect URL after payment completion"},"extraId":{"type":"number","example":1042,"description":"Merchant-defined order/reference ID"}}}}}},"responses":{"201":{"description":"Pre-invoice created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Encrypted pre-invoice ID — pass to the charge-invoice client","example":"abc123encrypted=="},"chargeLink":{"type":"string","format":"uri","description":"Full URL to redirect the customer to for coin selection","example":"https://pay.cigalpay.com/abc123encrypted=="},"ipn":{"type":"string","format":"uri"},"callback":{"type":"string","format":"uri"},"extraId":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"status":{"type":"object","properties":{"value":{"type":"string","example":"pending"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Missing required fields"}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/pre-invoice/{id}":{"get":{"summary":"Get a pre-invoice by ID","operationId":"getPreInvoiceById","tags":["Pre-Invoice"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Encrypted pre-invoice ID returned by POST /api/pre-invoice","example":"abc123encrypted=="}],"responses":{"200":{"description":"Pre-invoice details with available crypto amounts","content":{"application/json":{"schema":{"type":"object","properties":{"merchant":{"type":"object","description":"Merchant business info","properties":{"id":{"type":"string","description":"Encrypted merchant account ID"}}},"preInvoice":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","enum":["USD","EUR"]},"description":{"type":"string"},"status":{"type":"object","properties":{"value":{"type":"string","example":"pending"},"updatedAt":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"}}},"availableCurrencies":{"type":"array","description":"Fiat amount converted to each supported cryptocurrency","items":{"type":"object","properties":{"code":{"type":"string","example":"BTC"},"amount":{"type":"number","example":0.00028}}}}}}}}},"400":{"description":"Invalid or not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/charge-invoice":{"post":{"summary":"Charge an invoice with a selected coin","operationId":"chargeInvoice","tags":["Charge"],"description":"Called by the pre-invoice UI once the customer selects a cryptocurrency. Creates a real payment on the primary backend and returns the wallet address and payment ID.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chargeId","accountId","coins"],"properties":{"chargeId":{"type":"string","description":"Encrypted pre-invoice ID","example":"abc123encrypted=="},"accountId":{"type":"string","description":"Encrypted merchant account ID","example":"xyz456encrypted=="},"coins":{"type":"string","description":"Cryptocurrency code selected by the customer","example":"BTC","enum":["BTC","LTC","ETH","DOGE","DASH","BCH"]}}}}}},"responses":{"200":{"description":"Payment created — returns payment address and ID from the primary backend","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Payment ID — use with /getPaymentStatus on the primary backend"},"publicKey":{"type":"string","description":"Wallet address to display to the customer"},"amount":{"type":"number"},"currency":{"type":"string","example":"BTC"},"status":{"type":"string","example":"WAITING"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Missing fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean","example":true},"message":{"type":"string"}}}}}},"500":{"description":"Failed to create payment","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean","example":true},"message":{"type":"string"}}}}}}}}},"/health":{"get":{"summary":"Health check","operationId":"healthCheck","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"service":{"type":"string","example":"cigalpay-coins-api"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number","description":"Process uptime in seconds"}}}}}}}}}}}