{"openapi":"3.0.3","info":{"title":"TBL Pay Merchant API","version":"1.0.0","description":"All 11 /v1 merchant operations. Browser/admin/dev APIs are excluded. Contract documentation version, not a new runtime API release. Keys generated in the portal include payments:read, payments:write, webhooks:read only. Global default: 120 requests/minute per IP; 32 KiB request body. BTC mainnet is a pilot; other networks require qualification. See the integration guide for signed webhooks, quote expiry and error handling."},"servers":[{"url":"https://tbl-pay.com"}],"externalDocs":{"description":"Integration guide","url":"https://tbl-pay.com/api-docs/"},"security":[{"bearer":[]}],"paths":{"/v1/payment-intents":{"post":{"operationId":"createPayment","summary":"Create a payment; store-scoped key required","description":"Required scope: `payments:write`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:write","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedPayment"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Persist with this operation; reuse unchanged for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayment"}}}}},"get":{"operationId":"listPayments","summary":"Latest 100 payments; no pagination","description":"Required scope: `payments:read`. See /api-docs/ for workflow and operational limits. Keyset pagination: descending creation time and ID. created_from is inclusive; created_to exclusive. Keep filters unchanged while following next_cursor. Not a frozen snapshot.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"]}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"created_from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"store_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","confirming","paid","review","expired","cancelled"]}}]}},"/v1/payment-intents/{id}":{"get":{"operationId":"getPayment","summary":"Read current payment state","description":"Required scope: `payments:read`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/payment-intents/{id}/attempts":{"post":{"operationId":"createAttempt","summary":"Reserve a 15-minute quote; replay may return expired instructions","description":"Required scope: `payments:write`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:write","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attempt"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Persist with this operation; reuse unchanged for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttemptRequest"}}}}}},"/v1/payment-intents/{id}/cancel":{"post":{"operationId":"cancelPayment","summary":"Cancel pending/expired payment; otherwise return unchanged state","description":"Required scope: `payments:write`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:write","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/assets":{"get":{"operationId":"listAssets","summary":"Configured enabled assets; not a network readiness guarantee","description":"Required scope: `payments:read`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"payments:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}},"required":["data"]}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets":{"get":{"operationId":"listWallets","summary":"Latest 100 nondeleted wallets; extra scope required","description":"Required scope: `wallets:read`. See /api-docs/ for workflow and operational limits.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"wallets:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Wallet"}}},"required":["data"]}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets/{id}/receipts":{"get":{"operationId":"listReceipts","summary":"Latest 100 receipts; extra scope required","description":"Required scope: `wallets:read`. See /api-docs/ for workflow and operational limits. Keyset pagination: descending creation time and ID. created_from is inclusive; created_to exclusive. Keep filters unchanged while following next_cursor. Not a frozen snapshot.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"wallets:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Receipt"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"]}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"created_from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"asset_id","in":"query","required":false,"schema":{"type":"string","maxLength":80}}]}},"/v1/billing/summary":{"get":{"operationId":"legacyBillingSummary","summary":"Legacy EUR aggregate, not monthly USD debt","description":"Required scope: `billing:read`. See /api-docs/ for workflow and operational limits.","tags":["Legacy billing"],"security":[{"bearer":[]}],"x-required-scope":"billing:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacySummary"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"deprecated":true}},"/v1/billing/invoices/{id}":{"get":{"operationId":"legacyInvoice","summary":"Legacy EUR invoice; merchant-wide key only","description":"Required scope: `billing:read`. See /api-docs/ for workflow and operational limits.","tags":["Legacy billing"],"security":[{"bearer":[]}],"x-required-scope":"billing:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyInvoice"}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"deprecated":true}},"/v1/webhook-events":{"get":{"operationId":"listWebhookEvents","summary":"Latest 100 event metadata records; no replay or full payload","description":"Required scope: `webhooks:read`. See /api-docs/ for workflow and operational limits. Keyset pagination: descending creation time and ID. created_from is inclusive; created_to exclusive. Keep filters unchanged while following next_cursor. Not a frozen snapshot.","tags":["Merchant API"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventMetadata"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"]}}}},"default":{"description":"Application error. Proxy/network failures may have another format. See guide for HTTP status codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"created_from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"store_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","maxLength":80}}]}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Store server API key, never a portal session or browser credential."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","request_id","retryable"]}},"required":["error"]},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","confirming","paid","expired","cancelled","review"]},"version":{"type":"integer"},"amount":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR"]},"allowed_assets":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}},"required":["id","reference","status","version","amount","currency","allowed_assets","created_at"]},"CreatePayment":{"type":"object","properties":{"reference":{"type":"string","format":"uuid"},"amount":{"type":"string","pattern":"^(0|[1-9]\\d{0,12})(\\.\\d{1,2})?$","description":"Must be greater than zero."},"currency":{"type":"string","enum":["USD","EUR"]},"allowed_assets":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":80}},"return_route_id":{"type":"string","format":"uuid","description":"Reserved; currently unused. Does not configure a redirect."}},"required":["reference","amount","currency","allowed_assets"],"additionalProperties":false},"AttemptRequest":{"type":"object","properties":{"asset_id":{"type":"string","maxLength":80}},"required":["asset_id"],"additionalProperties":false},"Attempt":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"attempt_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string"},"recipient":{"type":"string"},"amount_atomic":{"type":"string"},"decimals":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"network":{"type":"string"}},"required":["payment_id","attempt_id","asset_id","recipient","amount_atomic","decimals","expires_at","network"]},"Asset":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"chain":{"type":"string"},"network":{"type":"string"},"decimals":{"type":"integer"},"priceId":{"type":"string"}},"required":["id","symbol","chain","network","decimals","priceId"]},"Wallet":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"chain":{"type":"string"},"network":{"type":"string"},"status":{"type":"string"},"coverage":{"type":"string"},"accepted_at":{"type":"string","format":"date-time"}},"required":["id","label","chain","network","status","coverage","accepted_at"]},"Receipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txid":{"type":"string"},"asset_id":{"type":"string"},"amount_atomic":{"type":"string"},"state":{"type":"string","enum":["observed","confirmed","orphaned"]},"classification":{"type":"string"},"block_time":{"type":"string","format":"date-time"}},"required":["id","txid","asset_id","amount_atomic","state","classification","block_time"]},"LegacySummary":{"type":"object","properties":{"currency":{"type":"string","enum":["EUR"]},"fee_eur":{"type":"string"},"rate_bps":{"type":"integer"},"provisional_count":{"type":"string"},"exact":{"type":"object","properties":{"numerator":{"type":"string"},"denominator":{"type":"string"}},"required":["numerator","denominator"]}},"required":["currency","fee_eur","rate_bps","provisional_count","exact"]},"LegacyInvoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"merchant_id":{"type":"string","format":"uuid"},"period":{"type":"string"},"total_minor":{"type":"string"},"status":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"environment":{"type":"string"}},"required":["id","merchant_id","period","total_minor","status","due_at","created_at","environment"]},"EventMetadata":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","created_at"]},"WebhookEvent":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"type":{"type":"string"},"schema_version":{"type":"integer","enum":[1]},"occurred_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"},"status":{"type":"string"},"version":{"type":"integer"},"amount":{"type":"string"},"currency":{"type":"string"}},"required":["payment_id"]}},"required":["event_id","type","schema_version","occurred_at","data"]},"CreatedPayment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","confirming","paid","expired","cancelled","review"]},"version":{"type":"integer"},"amount":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR"]},"checkout_url":{"type":"string","format":"uri"}},"required":["id","reference","status","version","amount","currency","checkout_url"]}}}}