{"openapi":"3.1.0","info":{"title":"AMPR — non-custodial crypto payment gateway","version":"0.1.0","description":"Accept crypto payments non-custodially: funds settle directly to the merchant, only the fee accrues to AMPR. Authenticate merchant endpoints with your API key as a Bearer token. Payer-facing checkout and public status endpoints need no auth (the invoice id is the capability)."},"servers":[{"url":"https://ampr.78-17-151-47.sslip.io"}],"tags":[{"name":"Invoices"},{"name":"Refunds"},{"name":"Merchant config"},{"name":"Public"},{"name":"Admin"}],"security":[{"apiKey":[]}],"paths":{"/v1/invoices":{"post":{"tags":["Invoices"],"summary":"Create an invoice","description":"Returns a checkout URL and per-asset payment details. Pass a unique `Idempotency-Key` header to make retries safe. `rate` is optional when the server has a rate provider configured.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoice"}}}},"responses":{"201":{"description":"Created (or replayed for a repeated Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Invoices"],"summary":"List invoices","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200,"default":50}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}}}}}}},"/v1/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Get an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}/payments":{"get":{"tags":["Invoices"],"summary":"List on-chain payments observed for an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/v1/invoices/{id}/refunds":{"post":{"tags":["Refunds"],"summary":"Request a refund","description":"Non-custodial: YOU send the refund from your own wallet, then call `/v1/refunds/{id}/complete` with the tx hash. Amount defaults to the full remaining refundable; to_address defaults to the original payer. The service fee is not refunded.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefund"}}}},"responses":{"201":{"description":"Created"},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Refunds"],"summary":"List refunds for an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/v1/refunds/{id}/complete":{"post":{"tags":["Refunds"],"summary":"Mark a refund completed (record the tx hash)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tx_hash"],"properties":{"tx_hash":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets":{"get":{"tags":["Merchant config"],"summary":"List receiving wallets","responses":{"200":{"description":"OK"}}},"post":{"tags":["Merchant config"],"summary":"Register a receiving wallet (xpub or address)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWallet"}}}},"responses":{"201":{"description":"Created"},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"get":{"tags":["Merchant config"],"summary":"List webhook endpoints","responses":{"200":{"description":"OK"}}},"post":{"tags":["Merchant config"],"summary":"Register a webhook endpoint (returns the signing secret once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https only; private/loopback hosts rejected"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created"},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/summary":{"get":{"tags":["Merchant config"],"summary":"Settled totals per asset","responses":{"200":{"description":"OK"}}}},"/public/invoices/{id}":{"get":{"tags":["Public"],"summary":"Public invoice status (no auth) — for checkout polling","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/invoices":{"get":{"tags":["Admin"],"summary":"List held invoices awaiting a compliance decision","security":[{"adminKey":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["held"]}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/invoices/{id}/release":{"post":{"tags":["Admin"],"summary":"Release a held invoice (compliance)","security":[{"adminKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/invoices/{id}/cancel":{"post":{"tags":["Admin"],"summary":"Cancel a held invoice (compliance)","security":[{"adminKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Merchant API key (`ampr_sk_…`)"},"adminKey":{"type":"apiKey","in":"header","name":"x-admin-key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"CreateInvoice":{"type":"object","required":["price","currency","assets"],"properties":{"price":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"129.90"},"currency":{"type":"string","example":"USD"},"order_id":{"type":"string"},"fee_bps":{"type":"integer","minimum":0,"maximum":500,"default":100},"ttl_seconds":{"type":"integer","maximum":86400,"default":3600},"description":{"type":"string"},"metadata":{"type":"object"},"assets":{"type":"array","minItems":1,"items":{"type":"object","required":["asset"],"properties":{"asset":{"type":"string","enum":["USDT_TRON","USDC_BASE","USDC_ETHEREUM","ETH_ETHEREUM","ETH_BASE","USDT_ETHEREUM","USDT_BSC","USDC_POLYGON","USDC_ARBITRUM","USDC_SOLANA","USDT_SOLANA","SOL_SOLANA","ETH_ARBITRUM","BNB_BSC","POL_POLYGON","BTC"]},"rate":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"quote per 1 asset; optional if a rate provider is configured"}}}}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","pending","underpaid","overpaid","confirming","held","paid","expired","canceled"]},"checkout_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"addresses":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string"},"chain":{"type":"string"},"amount":{"type":"string","description":"expected amount in integer minor units"}}}}}},"CreateRefund":{"type":"object","properties":{"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"decimal; blank = full remaining"},"to_address":{"type":"string","description":"blank = original payer"}}},"RegisterWallet":{"type":"object","required":["chain","kind"],"properties":{"chain":{"type":"string","enum":["tron","bitcoin","solana","ethereum","base","bsc","polygon","arbitrum"]},"kind":{"type":"string","enum":["address","xpub"]},"address":{"type":"string"},"xpub":{"type":"string"}}}}},"x-webhooks":{"payment.confirmed":{"description":"Sent when an invoice reaches `paid`. Verify the `X-AMPR-Signature: t=…,v1=…` header (HMAC-SHA256 of `t.rawBody` with your endpoint secret) and re-check status via GET /v1/invoices/{id} before fulfilling."},"refund.completed":{"description":"Sent when a refund is marked completed."}}}