{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Tole Payments API","version":"1.0.0","description":"Machine-readable contract for Tole public payment and sandbox APIs. Sandbox data is isolated by connection and never calls Kaspi."},"servers":[{"url":"/v1"}],"tags":[{"name":"Payments","description":"Live provider-backed payment operations."},{"name":"Sandbox","description":"Durable test payment operations. Never routed to Kaspi."},{"name":"API Keys","description":"JWT-authenticated public API credential management."},{"name":"Webhooks","description":"JWT-authenticated webhook endpoint and delivery management."},{"name":"Billing","description":"JWT-authenticated plans, subscription, usage and invoices."}],"paths":{"/invoices/client-info":{"post":{"operationId":"lookupInvoiceClient","summary":"Validate an invoice client","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceClientRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices":{"post":{"operationId":"createInvoice","summary":"Create an invoice","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRequest"}}}},"responses":{"201":{"description":"Resource accepted and created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices/history":{"get":{"operationId":"listInvoiceHistory","summary":"List invoice history","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices/{operationId}":{"get":{"operationId":"getInvoice","summary":"Get invoice details","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices/{operationId}/cancel":{"post":{"operationId":"cancelInvoice","summary":"Cancel an invoice","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Mutation completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/qr":{"post":{"operationId":"createQr","summary":"Create a payment QR","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQrRequest"}}}},"responses":{"201":{"description":"Resource accepted and created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/qr/{operationId}":{"get":{"operationId":"getQr","summary":"Get QR details","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/history/operations":{"get":{"operationId":"listPaymentOperations","summary":"List provider payment operations","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"endDate","in":"query","required":true,"description":"Inclusive payment-history calendar date in UTC.","schema":{"type":"string","format":"date"}},{"name":"lastTransactionDate","in":"query","schema":{"type":"string"}},{"name":"statementPeriodCode","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/history/operations/{operationId}":{"get":{"operationId":"getPaymentOperation","summary":"Get provider operation details","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"operationMethod","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/refunds":{"post":{"operationId":"createRefund","summary":"Create a refund","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}}},"responses":{"200":{"description":"Mutation completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/payment-intents/invoices/{paymentIntentId}":{"get":{"operationId":"getInvoicePaymentIntent","summary":"Get durable invoice status","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"paymentIntentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/payment-intents/qr/{paymentIntentId}":{"get":{"operationId":"getQrPaymentIntent","summary":"Get durable QR status","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":false,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"paymentIntentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commands/{commandId}":{"get":{"operationId":"getCommand","summary":"Get idempotent command status","tags":["Payments"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api-keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","tags":["API Keys"],"security":[{"AccessToken":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"API key page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createApiKey","summary":"Create an API key and return its secret once","tags":["API Keys"],"security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"API key created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api-keys/{apiKeyId}":{"put":{"operationId":"updateApiKey","summary":"Replace API key name and grants","tags":["API Keys"],"security":[{"AccessToken":[]}],"parameters":[{"name":"apiKeyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyRequest"}}}},"responses":{"200":{"description":"API key updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api-keys/{apiKeyId}/revoke":{"post":{"operationId":"revokeApiKey","summary":"Revoke an API key","tags":["API Keys"],"security":[{"AccessToken":[]}],"parameters":[{"name":"apiKeyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API key revoked or already revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiKeyResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"AccessToken":[]}],"responses":{"200":{"description":"Webhook endpoints.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint and return its signing secret once","tags":["Webhooks"],"security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"201":{"description":"Webhook endpoint created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or webhook entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhook-endpoints/{endpointId}/disable":{"post":{"operationId":"disableWebhookEndpoint","summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"AccessToken":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Webhook endpoint disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"AccessToken":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","delivered","dead_letter"]}}],"responses":{"200":{"description":"Webhook deliveries.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhook-deliveries/{deliveryId}/replay":{"post":{"operationId":"replayWebhookDelivery","summary":"Replay a dead-letter webhook delivery","tags":["Webhooks"],"security":[{"AccessToken":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Webhook delivery queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/overview":{"get":{"operationId":"getBillingOverview","summary":"Get subscription, usage and invoice overview","tags":["Billing"],"security":[{"AccessToken":[]}],"responses":{"200":{"description":"Billing overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingOverview"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/plans":{"get":{"operationId":"listBillingPlans","summary":"List public billing plans","tags":["Billing"],"security":[{"AccessToken":[]}],"responses":{"200":{"description":"Billing plans.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BillingPlan"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/invoices/{invoiceId}":{"get":{"operationId":"getBillingInvoice","summary":"Get a billing invoice","tags":["Billing"],"security":[{"AccessToken":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Billing invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingInvoice"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/checkout":{"post":{"operationId":"createBillingCheckout","summary":"Create or resume a Kaspi subscription checkout","tags":["Billing"],"security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillingCheckoutRequest"}}}},"responses":{"201":{"description":"Billing checkout created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckout"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/checkout/{checkoutId}":{"get":{"operationId":"getBillingCheckout","summary":"Get an owner-scoped subscription checkout","tags":["Billing"],"security":[{"AccessToken":[]}],"parameters":[{"name":"checkoutId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Billing checkout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckout"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/webhooks/kaspi":{"post":{"operationId":"receiveKaspiBillingWebhook","summary":"Receive a signed Kaspi billing event","description":"The signature is HMAC-SHA256 over the exact raw JSON body.","tags":["Billing"],"security":[],"parameters":[{"name":"X-Webhook-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^sha256=[0-9a-fA-F]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Webhook accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid webhook payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid webhook signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Subscription checkout is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/subscription/cancel":{"post":{"operationId":"cancelBillingSubscription","summary":"Cancel the subscription at period end","tags":["Billing"],"security":[{"AccessToken":[]}],"responses":{"200":{"description":"Subscription cancellation scheduled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSubscription"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Resource state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/connections":{"post":{"operationId":"createSandboxConnection","summary":"Create an isolated sandbox connection","tags":["Sandbox"],"security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSandboxConnectionRequest"}}}},"responses":{"201":{"description":"Sandbox connection created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxConnectionResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/invoices/client-info":{"post":{"operationId":"sandboxLookupInvoiceClient","summary":"Validate a synthetic invoice client","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceClientRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/invoices":{"post":{"operationId":"sandboxCreateInvoice","summary":"Create a synthetic invoice","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRequest"}}}},"responses":{"201":{"description":"Resource accepted and created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/invoices/history":{"get":{"operationId":"sandboxListInvoices","summary":"List durable sandbox invoices","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/invoices/{operationId}":{"get":{"operationId":"sandboxGetInvoice","summary":"Get a sandbox invoice","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/invoices/{operationId}/cancel":{"post":{"operationId":"sandboxCancelInvoice","summary":"Cancel a sandbox invoice","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Mutation completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/qr":{"post":{"operationId":"sandboxCreateQr","summary":"Create a synthetic payment QR","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQrRequest"}}}},"responses":{"201":{"description":"Resource accepted and created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/qr/{operationId}":{"get":{"operationId":"sandboxGetQr","summary":"Get a sandbox QR","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/history/operations":{"get":{"operationId":"sandboxListPaymentOperations","summary":"List durable sandbox payments","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"endDate","in":"query","required":true,"description":"Inclusive payment-history calendar date in UTC.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/history/operations/{operationId}":{"get":{"operationId":"sandboxGetPaymentOperation","summary":"Get a sandbox payment","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/refunds":{"post":{"operationId":"sandboxCreateRefund","summary":"Refund a paid sandbox QR payment","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one mutation. Reusing it with a different request returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}}},"responses":{"200":{"description":"Mutation completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"202":{"description":"The durable command is in progress or its provider outcome is unknown.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommandPendingResponse"},{"$ref":"#/components/schemas/CommandOutcomeUnknownResponse"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription or billing entitlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency key conflict or invalid payment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/payment-intents/{paymentIntentId}":{"get":{"operationId":"sandboxGetPaymentIntent","summary":"Get durable sandbox payment status","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"paymentIntentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/payment-intents/{paymentIntentId}/simulate":{"post":{"operationId":"sandboxSimulatePaymentStatus","summary":"Simulate a terminal payment status","description":"Requires the sandbox:simulate permission for the selected sandbox connection.","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"X-Tole-Connection-Id","in":"header","required":true,"description":"UUID of the connection authorized for this API key.","schema":{"type":"string","format":"uuid"}},{"name":"paymentIntentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulatePaymentRequest"}}}},"responses":{"200":{"description":"Updated payment intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sandbox/commands/{commandId}":{"get":{"operationId":"sandboxGetCommand","summary":"Get sandbox command status","tags":["Sandbox"],"security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential is not authorized for the connection or permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or billing usage limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The upstream payment provider rejected or could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Persistence or required infrastructure dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{"paymentEvent":{"post":{"summary":"Payment event delivery","description":"The exact JSON body is signed as v1=hex(HMAC-SHA256(secret, \"<webhook-id>.<webhook-timestamp>.<body>\"))). Sandbox events contain data.environment=sandbox.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"integer"}},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentWebhookEvent"}}}},"responses":{"200":{"description":"Delivery accepted."}}}}},"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"tole_sk_test_v1 or tole_sk_live_v1","description":"Public API key. Sandbox accepts only the test namespace."},"AccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"EmptyObject":{"type":"object","additionalProperties":false,"maxProperties":0},"InvoiceClientRequest":{"type":"object","additionalProperties":false,"required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","pattern":"^\\+?7[0-9]{10}$"}}},"CreateInvoiceRequest":{"type":"object","additionalProperties":false,"required":["phoneNumber","amount"],"properties":{"phoneNumber":{"type":"string","pattern":"^\\+?7[0-9]{10}$"},"amount":{"type":"integer","minimum":1,"maximum":100000000},"comment":{"type":"string","maxLength":200}}},"CreateQrRequest":{"type":"object","additionalProperties":false,"required":["amount"],"dependentRequired":{"latitude":["longitude"],"longitude":["latitude"]},"properties":{"amount":{"type":"integer","minimum":1,"maximum":100000000},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}}},"CreateRefundRequest":{"type":"object","additionalProperties":false,"required":["operationId","returnAmount"],"properties":{"operationId":{"type":"string","format":"uuid"},"returnAmount":{"type":"integer","minimum":1,"maximum":100000000}}},"ApiKeyPermission":{"type":"string","enum":["invoice:create","invoice:read","invoice:cancel","qr:create","qr:read","history:read","refund:create","sandbox:simulate"]},"ApiKeyGrantRequest":{"type":"object","additionalProperties":false,"required":["connectionId","permissions"],"properties":{"connectionId":{"type":"string","format":"uuid"},"permissions":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"$ref":"#/components/schemas/ApiKeyPermission"}}}},"ApiKeyGrant":{"type":"object","additionalProperties":false,"required":["connectionId","connectionName","environment","permissions"],"properties":{"connectionId":{"type":"string","format":"uuid"},"connectionName":{"type":"string"},"environment":{"type":"string","enum":["live","sandbox"]},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyPermission"}}}},"CreateApiKeyRequest":{"type":"object","additionalProperties":false,"required":["name","grants"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"grants":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ApiKeyGrantRequest"}}}},"UpdateApiKeyRequest":{"type":"object","additionalProperties":false,"required":["name","grants","expectedRevision"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"grants":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ApiKeyGrantRequest"}},"expectedRevision":{"type":"integer","minimum":1,"maximum":2147483646}}},"ApiKey":{"type":"object","additionalProperties":false,"required":["id","name","keyPrefix","status","revision","lastUsedAt","revokedAt","createdAt","updatedAt","grants"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"revision":{"type":"integer","minimum":1},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"grants":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyGrant"}}}},"ApiKeyListResponse":{"type":"object","additionalProperties":false,"required":["apiKeys","nextCursor"],"properties":{"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"nextCursor":{"type":["string","null"]}}},"CreateApiKeyResponse":{"type":"object","additionalProperties":false,"required":["apiKey","secret"],"properties":{"apiKey":{"$ref":"#/components/schemas/ApiKey"},"secret":{"type":"string","description":"Returned once. Store it before leaving the response.","pattern":"^tole_sk_(?:live|test)_v1\\.[0-9a-f-]{36}\\.[A-Za-z0-9_-]{43}$"}}},"RevokeApiKeyResponse":{"type":"object","additionalProperties":false,"required":["kind","apiKey"],"properties":{"kind":{"type":"string","enum":["revoked","already_revoked"]},"apiKey":{"$ref":"#/components/schemas/ApiKey"}}},"CreateWebhookEndpointRequest":{"type":"object","additionalProperties":false,"required":["name","url"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"}}},"WebhookEndpoint":{"type":"object","additionalProperties":false,"required":["id","name","url","status","createdAt","updatedAt","disabledAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"disabledAt":{"type":["string","null"],"format":"date-time"}}},"CreateWebhookEndpointResponse":{"type":"object","additionalProperties":false,"required":["endpoint","secret"],"properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"Returned once. Use it to verify webhook signatures.","pattern":"^whsec_[A-Za-z0-9_-]{43}$"}}},"WebhookDelivery":{"type":"object","additionalProperties":false,"required":["id","endpointId","eventId","eventType","status","attemptCount","nextAttemptAt","lastFailureCode","responseStatus","deliveredAt","deadLetterAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"endpointId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"status":{"type":"string","enum":["pending","processing","delivered","dead_letter"]},"attemptCount":{"type":"integer","minimum":0},"nextAttemptAt":{"type":["string","null"],"format":"date-time"},"lastFailureCode":{"type":["string","null"]},"responseStatus":{"type":["integer","null"],"minimum":100,"maximum":599},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deadLetterAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BillingMetric":{"type":"string","enum":["invoice_create_live","invoice_cancel_live","qr_create_live","refund_create_live","payment_mutation_sandbox","active_webhook_endpoints"]},"BillingEntitlement":{"type":"object","additionalProperties":false,"required":["metric","scope","limit"],"properties":{"metric":{"$ref":"#/components/schemas/BillingMetric"},"scope":{"type":"string","enum":["monthly","current"]},"limit":{"type":["integer","null"],"minimum":0}}},"BillingUsage":{"type":"object","additionalProperties":false,"required":["metric","scope","limit","consumed","reserved","remaining"],"properties":{"metric":{"$ref":"#/components/schemas/BillingMetric"},"scope":{"type":"string","enum":["monthly","current"]},"limit":{"type":["integer","null"],"minimum":0},"consumed":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"remaining":{"type":["integer","null"],"minimum":0}}},"BillingPlan":{"type":"object","additionalProperties":false,"required":["code","version","name","priceMonthlyKzt","currency","isPublic","entitlements"],"properties":{"code":{"type":"string"},"version":{"type":"integer","minimum":1},"name":{"type":"string"},"priceMonthlyKzt":{"type":["integer","null"],"minimum":0},"currency":{"const":"KZT"},"isPublic":{"type":"boolean"},"entitlements":{"type":"array","items":{"$ref":"#/components/schemas/BillingEntitlement"}}}},"BillingSubscription":{"type":"object","additionalProperties":false,"required":["id","status","plan","currentPeriodStart","currentPeriodEnd","trialEndsAt","cancelAtPeriodEnd","revision"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["trialing","active","past_due","cancelled"]},"plan":{"$ref":"#/components/schemas/BillingPlan"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"trialEndsAt":{"type":["string","null"],"format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"revision":{"type":"integer","minimum":1}}},"BillingInvoice":{"type":"object","additionalProperties":false,"required":["id","number","status","planCode","planName","amountKzt","currency","periodStart","periodEnd","dueAt","paidAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"status":{"type":"string","enum":["open","paid","void","uncollectible"]},"planCode":{"type":"string"},"planName":{"type":"string"},"amountKzt":{"type":"integer","minimum":0},"currency":{"const":"KZT"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"CreateBillingCheckoutRequest":{"type":"object","additionalProperties":false,"required":["planCode"],"properties":{"planCode":{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,63}$"}}},"BillingCheckout":{"type":"object","additionalProperties":false,"required":["id","status","planCode","planName","amountKzt","currency","paymentUrl","receiptUrl","expiresAt","paidAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["creating","pending","outcome_unknown","paid","failed","expired","review"]},"planCode":{"type":"string"},"planName":{"type":"string"},"amountKzt":{"type":"integer","minimum":1},"currency":{"const":"KZT"},"paymentUrl":{"type":["string","null"],"format":"uri"},"receiptUrl":{"type":["string","null"],"format":"uri"},"expiresAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"BillingOverview":{"type":"object","additionalProperties":false,"required":["enabled","checkoutEnabled","checkout","subscription","usage","invoices"],"properties":{"enabled":{"type":"boolean"},"checkoutEnabled":{"type":"boolean"},"checkout":{"oneOf":[{"$ref":"#/components/schemas/BillingCheckout"},{"type":"null"}]},"subscription":{"oneOf":[{"$ref":"#/components/schemas/BillingSubscription"},{"type":"null"}]},"usage":{"type":"array","items":{"$ref":"#/components/schemas/BillingUsage"}},"invoices":{"type":"array","items":{"$ref":"#/components/schemas/BillingInvoice"}}}},"CreateSandboxConnectionRequest":{"type":"object","additionalProperties":false,"required":["displayName"],"properties":{"displayName":{"type":"string","minLength":1,"maxLength":100}}},"SimulatePaymentRequest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["paid","cancelled","expired","failed"]}}},"PaymentIntent":{"type":"object","additionalProperties":false,"required":["id","kind","status","amount","currency","revision","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["invoice","qr"]},"status":{"type":"string","enum":["pending","paid","cancelled","expired","failed","partially_refunded","refunded"]},"amount":{"type":"number"},"refundedAmount":{"type":"number"},"currency":{"const":"KZT"},"revision":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"terminalAt":{"type":["string","null"],"format":"date-time"},"lastReconciledAt":{"type":["string","null"],"format":"date-time"},"environment":{"type":"string","enum":["live","sandbox"]}}},"SuccessResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"object"},"commandId":{"type":"string","format":"uuid"}}},"PaymentIntentResponse":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/PaymentIntent"}}},"CommandPendingResponse":{"type":"object","additionalProperties":false,"required":["ok","kind","commandId","replayed"],"properties":{"ok":{"const":false},"kind":{"const":"in_progress"},"commandId":{"type":"string","format":"uuid"},"replayed":{"const":true}}},"CommandOutcomeUnknownResponse":{"type":"object","additionalProperties":false,"required":["ok","kind","commandId","replayed"],"properties":{"ok":{"const":false},"kind":{"const":"outcome_unknown"},"commandId":{"type":"string","format":"uuid"},"replayed":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"}}},"SandboxConnectionResponse":{"type":"object","required":["id","providerMode","status","displayName"],"properties":{"id":{"type":"string","format":"uuid"},"providerMode":{"const":"sandbox"},"status":{"const":"active"},"displayName":{"type":"string"}}},"PaymentWebhookEvent":{"type":"object","additionalProperties":false,"required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["payment.created","payment.paid","payment.cancelled","payment.expired","payment.failed","payment.partially_refunded","payment.refunded","refund.reserved","refund.succeeded","operation.succeeded","operation.rejected","operation.outcome_unknown","refund.rejected","refund.outcome_unknown"]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"environment":{"type":"string","enum":["live","sandbox"]}}}}}}}}