{"openapi":"3.1.0","info":{"title":"SGRON merchant API","version":"1","description":"Smart Geo Router. Create an invoice, send the payer to checkout_url (or open it with the widget /assets/sgron.js), and take the result from the invoice.paid webhook. Funds go from the payment provider or the payer wallet straight to your wallet; the SGRON fee is billed separately by statement."},"servers":[{"url":"https://pay.sgron.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-sgron-key"},"signature":{"type":"apiKey","in":"header","name":"sgron-signature","description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with the merchant secret>; 5 minute window"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]},"InvoiceCreate":{"type":"object","required":["amount","currency","network","merchant_order_id"],"properties":{"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","description":"USD, EUR, USDC and others with a reference rate"},"asset":{"type":"string","enum":["USDC","USDT"],"description":"Payout asset; your account default when left out"},"network":{"type":"string","enum":["ethereum","base","polygon","arbitrum","bsc","tron","base_sepolia"]},"wallet_address":{"type":"string","description":"Your wallet; defaults to the wallet set in the console for the network"},"merchant_order_id":{"type":"string","description":"Unique per merchant"},"callback_url":{"type":"string","format":"uri"},"success_url":{"type":"string","format":"uri","description":"https; \"Return to the store\" after payment"},"expires_in":{"type":"integer","minimum":60,"maximum":86400,"default":1800}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","routed","pending","awaiting_method","confirming","paid","declined","expired"]},"amount":{"type":"number"},"currency":{"type":"string"},"asset":{"type":"string"},"network":{"type":"string"},"wallet_address":{"type":"string"},"merchant_order_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"tx_hash":{"type":"string"},"amount_received":{"type":"string"},"success_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"checkout_url":{"type":"string","description":"Only in the create response; the token in the fragment opens the page"}}},"Statement":{"type":"object","properties":{"id":{"type":"string"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"asset":{"type":"string"},"network":{"type":"string"},"total":{"type":"string"},"accruals":{"type":"integer"},"pay_to":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["open","paid"]}}},"Webhook":{"type":"object","description":"POST to your webhook URL, signed in sgron-signature like requests","properties":{"event":{"type":"string","enum":["invoice.paid","invoice.funded","invoice.underfunded","invoice.declined","invoice.expired","invoice.amount_mismatch","invoice.overpaid","invoice.refunded"]},"invoice_id":{"type":"string"},"merchant_order_id":{"type":"string"},"tx_hash":{"type":"string"},"amount_received":{"type":"string"},"fee_bps":{"type":"integer"},"fee_amount":{"type":"string"}}}}},"paths":{"/v1/invoices":{"post":{"summary":"Create an invoice","security":[{"apiKey":[],"signature":[]}],"parameters":[{"name":"idempotency-key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key or bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"fee_statement_overdue"},"409":{"description":"duplicate_merchant_order_id"}}},"get":{"summary":"List invoices, newest first","security":[{"apiKey":[],"signature":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Invoice id or merchant_order_id"},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Page of invoices","content":{"application/json":{"schema":{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key or bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}":{"get":{"summary":"Invoice status","security":[{"apiKey":[],"signature":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key or bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found"}}}},"/v1/fees":{"get":{"summary":"SGRON fee rate, statements and accruals","security":[{"apiKey":[],"signature":[]}],"responses":{"200":{"description":"Fees"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key or bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fees/statements":{"post":{"summary":"Issue a fee statement now for everything accrued so far (daily statements are issued on their own)","security":[{"apiKey":[],"signature":[]}],"responses":{"200":{"description":"Nothing to bill; statement is null"},"201":{"description":"Issued","content":{"application/json":{"schema":{"type":"object","properties":{"statement":{"$ref":"#/components/schemas/Statement"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key or bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}