{"openapi":"3.1.0","paths":{"/api/v1/balance":{"get":{"description":"Settled USDC held for you in the ZyloPay settlement contract on the key's network, read from the chain. Withdraw it to your settlement wallet from the dashboard.\n\nRequired scope: `balance:read`.","operationId":"retrieveBalance","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve the balance","tags":["Balance"]}},"/api/v1/events":{"get":{"description":"Events of the last 30 days, newest first: the same objects webhooks deliver. Use it to catch up after downtime.\n\nRequired scope: `events:read`.","operationId":"listEvents","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"created_gte","required":false,"in":"query","description":"Only objects created at or after this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-09-01T00:00:00Z"]}},{"name":"created_lt","required":false,"in":"query","description":"Only objects created before this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-10-01T00:00:00Z"]}},{"name":"type","required":false,"in":"query","description":"An event type, or a family with `.*` (for example `payment_intent.*`).","schema":{"type":"string","examples":["payment.succeeded"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List events","tags":["Events"]}},"/api/v1/events/{id}":{"get":{"description":"An event by ID (30-day retention).\n\nRequired scope: `events:read`.","operationId":"retrieveEvent","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Event ID (`evt_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve an event","tags":["Events"]}},"/api/v1/payment_intents":{"post":{"description":"Ask one of your terminals to take a payment (server-driven checkout, for example from your POS or ordering system). The terminal picks the intent up, shows the amount and settles it when the customer taps; follow the outcome with webhooks (`payment_intent.*`, `payment.succeeded`) or by retrieving the intent. Live mode needs an approved business verification.\n\nRequired scope: `payments:write`.","operationId":"createPaymentIntent","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"Idempotency-Key","in":"header","description":"Required. A unique key per operation (a UUID v4). Retrying with the same key and body returns the first response (`Idempotent-Replayed: true`); a different body is refused with 409 `idempotency_key_reused`. Keys are kept 48 hours.","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentIntentRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Create a payment intent","tags":["Payment intents"]},"get":{"description":"Payment intents of your account in the key's mode, newest first: the ones you created and the ones your terminals opened.\n\nRequired scope: `payments:read`.","operationId":"listPaymentIntents","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"created_gte","required":false,"in":"query","description":"Only objects created at or after this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-09-01T00:00:00Z"]}},{"name":"created_lt","required":false,"in":"query","description":"Only objects created before this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-10-01T00:00:00Z"]}},{"name":"terminal","required":false,"in":"query","description":"Only intents of this terminal (`tml_…`).","schema":{"type":"string","examples":["tml_ZP-4821-K"]}},{"name":"source","required":false,"in":"query","description":"Who created the intent: your server (`api`) or the POS (`terminal`).","schema":{"type":"string","enum":["api","terminal"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List payment intents","tags":["Payment intents"]}},"/api/v1/payment_intents/{id}":{"get":{"description":"A payment intent by ID, with its current status.\n\nRequired scope: `payments:read`.","operationId":"retrievePaymentIntent","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Payment intent ID (`pi_…`).","schema":{"type":"string","examples":["pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a payment intent","tags":["Payment intents"]}},"/api/v1/payment_intents/{id}/cancel":{"post":{"description":"Cancel an intent that has not been paid (`requires_payment_method` or `requires_action`). Nothing is charged afterwards. An intent whose settlement was already sent (or whose payer already confirmed) cannot be canceled: refund it instead. Canceling a canceled intent returns it unchanged.\n\nRequired scope: `payments:write`.","operationId":"cancelPaymentIntent","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Payment intent ID (`pi_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Cancel a payment intent","tags":["Payment intents"]}},"/api/v1/payments":{"get":{"description":"Settled payments of your account in the key's mode, newest first. A payment appears once its settlement is indexed (about a second after the tap).\n\nRequired scope: `payments:read`.","operationId":"listPayments","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"created_gte","required":false,"in":"query","description":"Only objects created at or after this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-09-01T00:00:00Z"]}},{"name":"created_lt","required":false,"in":"query","description":"Only objects created before this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-10-01T00:00:00Z"]}},{"name":"status","required":false,"in":"query","description":"Filter by payment status.","schema":{"type":"string","enum":["succeeded","partially_refunded","refunded"]}},{"name":"terminal","required":false,"in":"query","description":"Only payments taken on this terminal (`tml_…`).","schema":{"type":"string","examples":["tml_ZP-4821-K"]}},{"name":"order_id","required":false,"in":"query","description":"Exact order ID.","schema":{"type":"string","examples":["A7K2Q9XZ"]}},{"name":"payer","required":false,"in":"query","description":"Payer wallet address (any case).","schema":{"type":"string","examples":["0x8ba1f109551bd432803012645ac136ddd64dba72"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List payments","tags":["Payments"]}},"/api/v1/payments/{id}":{"get":{"description":"A payment by ID.\n\nRequired scope: `payments:read`.","operationId":"retrievePayment","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Payment ID (`pay_…`).","schema":{"type":"string","examples":["pay_1042"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a payment","tags":["Payments"]}},"/api/v1/refunds":{"post":{"description":"Return all or part of a payment to the payer, from your merchant balance, on the payment's own network. The response is the refund: `succeeded` (mined), `pending` (sent, confirmation not seen yet: it resolves on its own, never retry with a new key) or `failed` (nothing moved; `failure_code`). Your account's refund window and daily limit apply.\n\nRequired scope: `refunds:write`.","operationId":"createRefund","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"Idempotency-Key","in":"header","description":"Required. A unique key per operation (a UUID v4). Retrying with the same key and body returns the first response (`Idempotent-Replayed: true`); a different body is refused with 409 `idempotency_key_reused`. Keys are kept 48 hours.","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Create a refund","tags":["Refunds"]},"get":{"description":"Refunds, newest first (from the POS, the dashboard and the API).\n\nRequired scope: `refunds:read`.","operationId":"listRefunds","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"created_gte","required":false,"in":"query","description":"Only objects created at or after this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-09-01T00:00:00Z"]}},{"name":"created_lt","required":false,"in":"query","description":"Only objects created before this time (ISO 8601).","schema":{"format":"date-time","type":"string","examples":["2026-10-01T00:00:00Z"]}},{"name":"payment","required":false,"in":"query","description":"Only refunds of this payment (`pay_…`).","schema":{"type":"string","examples":["pay_1042"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","succeeded","failed"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List refunds","tags":["Refunds"]}},"/api/v1/refunds/{id}":{"get":{"description":"A refund by ID.\n\nRequired scope: `refunds:read`.","operationId":"retrieveRefund","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Refund ID (`re_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a refund","tags":["Refunds"]}},"/api/v1/terminals":{"get":{"description":"POS terminals provisioned in the key's mode. Terminals are provisioned from the dashboard (they receive a device key once).\n\nRequired scope: `terminals:read`.","operationId":"listTerminals","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["active","inactive"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminalList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List terminals","tags":["Terminals"]}},"/api/v1/terminals/{id}":{"get":{"description":"A terminal by ID.\n\nRequired scope: `terminals:read`.","operationId":"retrieveTerminal","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Terminal ID (`tml_…`).","schema":{"type":"string","examples":["tml_ZP-4821-K"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Terminal"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a terminal","tags":["Terminals"]}},"/api/v1/webhook_deliveries/{id}":{"get":{"description":"A delivery with every attempt (`attempt_log`).\n\nRequired scope: `webhooks:read`.","operationId":"retrieveWebhookDelivery","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Delivery ID (`wdl_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a delivery","tags":["Webhooks"]}},"/api/v1/webhook_deliveries/{id}/retry":{"post":{"description":"Send the delivery's event to its endpoint again now, as a new delivery (one attempt), and return it.\n\nRequired scope: `webhooks:manage`.","operationId":"retryWebhookDelivery","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Delivery ID (`wdl_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Resend a delivery","tags":["Webhooks"]}},"/api/v1/webhook_endpoints":{"post":{"description":"Register a URL to receive events of this mode. The response carries the signing `secret` (`whsec_…`) once: verify every delivery's `ZyloPay-Signature` with it. Up to 16 endpoints per mode.\n\nRequired scope: `webhooks:manage`.","operationId":"createWebhookEndpoint","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Create a webhook endpoint","tags":["Webhooks"]},"get":{"description":"All webhook endpoints of this mode.\n\nRequired scope: `webhooks:read`.","operationId":"listWebhookEndpoints","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List webhook endpoints","tags":["Webhooks"]}},"/api/v1/webhook_endpoints/{id}":{"get":{"description":"A webhook endpoint by ID (never its secret).\n\nRequired scope: `webhooks:read`.","operationId":"retrieveWebhookEndpoint","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Retrieve a webhook endpoint","tags":["Webhooks"]},"patch":{"description":"Change the URL, subscribed events or description, or disable / re-enable the endpoint.\n\nRequired scope: `webhooks:manage`.","operationId":"updateWebhookEndpoint","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Update a webhook endpoint","tags":["Webhooks"]},"delete":{"description":"Stop all deliveries to the endpoint. Pending deliveries are dropped; the delivery log is kept.\n\nRequired scope: `webhooks:manage`.","operationId":"deleteWebhookEndpoint","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedWebhookEndpoint"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Delete a webhook endpoint","tags":["Webhooks"]}},"/api/v1/webhook_endpoints/{id}/deliveries":{"get":{"description":"The delivery log of the endpoint, newest first: status, attempts, last response.\n\nRequired scope: `webhooks:read`.","operationId":"listWebhookDeliveries","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Page size, 1-100.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer","examples":[20]}},{"name":"cursor","required":false,"in":"query","description":"The `next_cursor` of the previous page. Omit for the first (newest) page.","schema":{"maxLength":1024,"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","succeeded","failed"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"List deliveries of an endpoint","tags":["Webhooks"]}},"/api/v1/webhook_endpoints/{id}/rotate_secret":{"post":{"description":"Issue a new signing secret (returned once). For `expires_in_hours` (default 24) deliveries carry two `v1` signatures — new and previous secret — so you can deploy the new secret without dropping events.\n\nRequired scope: `webhooks:manage`.","operationId":"rotateWebhookSecret","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateWebhookSecretRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Rotate the signing secret","tags":["Webhooks"]}},"/api/v1/webhook_endpoints/{id}/test":{"post":{"description":"Deliver a `ping` event to the endpoint now (one attempt) and return the delivery, with your endpoint's response.\n\nRequired scope: `webhooks:manage`.","operationId":"sendTestWebhook","parameters":[{"name":"ZyloPay-Version","in":"header","description":"Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.","required":false,"schema":{"type":"string","enum":["2026-09-28"]}},{"name":"id","required":true,"in":"path","description":"Webhook endpoint ID (`we_…`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"400":{"description":"Invalid request (`invalid_request_error` / `idempotency_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"401":{"description":"Missing, invalid, expired or revoked API key (`authentication_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"403":{"description":"The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"409":{"description":"Conflict: idempotency key reused or in progress, or the object is in the wrong state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"429":{"description":"Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}},"500":{"description":"Internal error (`api_error`). Retry with the same `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ZyloPay-Version":{"$ref":"#/components/headers/ZyloPay-Version"}}}},"security":[{"ApiKey":[]}],"summary":"Send a test event","tags":["Webhooks"]}}},"info":{"title":"ZyloPay API","description":"The ZyloPay API lets your systems follow and drive in-store payments: list and look up\npayments, send a payment to one of your terminals, refund, and receive signed webhooks when\nanything changes. Payments settle in USDC on Monad in under a second.\n\n## Authentication\nSend a secret API key as a bearer token: `Authorization: Bearer zp_test_sk_…`. Create keys\nin the dashboard (Developers → API keys). The key decides the mode and network:\n\n| Key prefix | Mode | Network |\n|---|---|---|\n| `zp_test_sk_` | test (sandbox) | Monad testnet (10143) |\n| `zp_live_sk_` | live | Monad mainnet (143) |\n\nKeys carry scopes (`payments:read`, `payments:write`, `refunds:read`, `refunds:write`, `terminals:read`, `balance:read`, `events:read`, `webhooks:read`, `webhooks:manage`), an optional\nIP allowlist and an optional expiry. Rotating a key keeps the old one working for an overlap\nwindow (24 hours by default). Live keys need an approved business verification. Keep secret\nkeys on your servers; never embed them in apps or web pages.\n\n## Requests and responses\n- JSON bodies, `snake_case` fields, objects identified by prefixed IDs (`pay_`, `pi_`,\n  `re_`, `tml_`, `evt_`, `we_`, `wdl_`). Treat IDs as opaque strings (up to 255 chars).\n- Amounts are integers in USDC atoms (6 decimals: `1000000` = 1.00 USDC) with\n  `currency: \"usdc\"`. Timestamps are ISO 8601 in UTC.\n- Every response carries a `Request-Id` header; quote it to support.\n- Lists are cursor-paginated, newest first: `limit` (1-100, default 20) and `cursor` (the\n  previous page's `next_cursor`).\n\n## Errors\nErrors use HTTP status codes and one body shape:\n`{ \"error\": { \"type\", \"code\", \"message\", \"param\"?, \"request_id\" } }`. Branch on `type` and\n`code` (listed below and in `components.schemas.ApiErrorDetail`); never parse `message`.\n\n- `api_key_missing` (401, `authentication_error`): No API key was sent. Send `Authorization: Bearer <secret key>`.\n- `api_key_invalid` (401, `authentication_error`): The API key is malformed or unknown.\n- `api_key_expired` (401, `authentication_error`): The API key has passed its expiry (for example the overlap window of a rotation ended).\n- `api_key_revoked` (401, `authentication_error`): The API key was revoked.\n- `insufficient_scope` (403, `permission_error`): The API key lacks the scope this endpoint requires (see `required_scope` in the message).\n- `ip_not_allowed` (403, `permission_error`): The request IP is not in the API key's IP allowlist.\n- `publishable_key_not_allowed` (403, `permission_error`): Publishable keys cannot call this endpoint; use a secret key from your server.\n- `account_disabled` (403, `permission_error`): The merchant account is disabled. Read-only requests still work. Contact ZyloPay support.\n- `kyb_required` (403, `permission_error`): Live mode needs an approved business verification (KYB) for this action.\n- `account_restricted` (403, `permission_error`): An account involved in this action cannot be used with ZyloPay right now. Nothing was done. Contact ZyloPay support.\n- `parameter_invalid` (400, `invalid_request_error`): A parameter has an invalid value (see `param`).\n- `parameter_missing` (400, `invalid_request_error`): A required parameter is missing (see `param`).\n- `parameter_unknown` (400, `invalid_request_error`): The request contains a parameter the endpoint does not accept (see `param`).\n- `api_version_invalid` (400, `invalid_request_error`): The `ZyloPay-Version` header names a version that does not exist.\n- `network_mismatch` (400, `invalid_request_error`): An `X-Network` header was sent that contradicts the API key's mode. API keys choose the network; omit the header.\n- `cursor_invalid` (400, `invalid_request_error`): The pagination cursor is malformed or belongs to another list.\n- `resource_missing` (404, `invalid_request_error`): No such object for this account and mode.\n- `account_not_live` (409, `invalid_request_error`): The merchant is not registered on this network yet (go live from the dashboard first).\n- `terminal_inactive` (409, `invalid_request_error`): The terminal is deactivated.\n- `payment_intent_unexpected_state` (409, `invalid_request_error`): The payment intent is not in a state that allows this action (see `message`).\n- `amount_too_large` (400, `invalid_request_error`): The amount exceeds what is allowed (for a refund: the amount still refundable).\n- `payment_already_refunded` (409, `invalid_request_error`): The payment has already been fully refunded.\n- `refund_window_expired` (409, `invalid_request_error`): The payment is older than the refund window of the account.\n- `refund_daily_limit_reached` (409, `invalid_request_error`): The account's daily refund limit would be exceeded.\n- `refund_in_progress` (409, `invalid_request_error`): Another refund of this payment is being sent; retry after it completes.\n- `webhook_url_invalid` (400, `invalid_request_error`): The URL is not a valid absolute http(s) URL, uses http in live mode, or carries credentials.\n- `webhook_url_forbidden` (400, `invalid_request_error`): The URL resolves to a private, loopback, link-local or otherwise reserved address.\n- `webhook_endpoint_limit_reached` (400, `invalid_request_error`): The account has the maximum number of webhook endpoints for this mode.\n- `webhook_endpoint_disabled` (409, `invalid_request_error`): The webhook endpoint is disabled; enable it first.\n- `idempotency_key_required` (400, `idempotency_error`): This endpoint moves money and requires an `Idempotency-Key` header.\n- `idempotency_key_invalid` (400, `idempotency_error`): The `Idempotency-Key` must be 1-255 printable ASCII characters.\n- `idempotency_key_reused` (409, `idempotency_error`): The `Idempotency-Key` was already used with a different request (method, path or body).\n- `idempotency_request_in_progress` (409, `idempotency_error`): A request with this `Idempotency-Key` is still being processed (or was interrupted). Do not retry with a new key before checking the outcome.\n- `rate_limited` (429, `rate_limit_error`): Too many requests for this API key. Wait for `Retry-After` seconds.\n- `internal_error` (500, `api_error`): Something went wrong on ZyloPay's side. A retry with the same `Idempotency-Key` replays this error: check the object, then retry with a new key only if nothing happened.\n- `service_unavailable` (503, `api_error`): A dependency is temporarily unavailable. A retry with the same `Idempotency-Key` replays this error: check the object, then retry later with a new key only if nothing happened.\n- `request_timeout` (503, `api_error`): The request exceeded its time budget and keeps running. Retry with the same `Idempotency-Key` (it never runs twice): you get its real outcome once it finished, `idempotency_request_in_progress` until then.\n\nA declined payment is not an HTTP error: the payment intent reports it in\n`last_payment_error.code`:\n\n- `pass_revoked`: The wallet pass was revoked.\n- `pass_frozen`: The wallet pass is frozen.\n- `pass_wrong_network`: The wallet pass was issued for the other network.\n- `authorization_required`: The wallet pass has no payment authorization; the payer must re-create it.\n- `authorization_expired`: The payer's spending approval expired; the payer must renew the pass.\n- `amount_exceeds_approval`: The amount is above the payer's spending approval.\n- `payer_frozen`: The payer's account is frozen.\n- `terminal_daily_limit`: The terminal reached its daily volume cap.\n- `risk_declined`: The payment was declined by risk rules.\n- `step_up_denied`: The payer or the cashier declined the confirmation request.\n- `step_up_expired`: The payer did not confirm in time.\n- `session_invalid`: The payment session was invalid, expired or already used.\n- `order_already_paid`: Another payment of this `order_id` is settled or in progress; nothing was charged by this attempt. Check that payment before charging again.\n- `credential_invalid`: The pass credential presented at the terminal is unknown or invalid.\n- `merchant_disabled`: The merchant account is disabled.\n- `kyb_required`: Live payments need an approved business verification.\n- `account_restricted`: The payer's account cannot be used with ZyloPay right now. Nothing was charged.\n- `settlement_failed`: The on-chain settlement failed; nothing was charged.\n- `settlement_reverted`: The on-chain transaction reverted; nothing was charged.\n- `refund_failed`: The on-chain refund failed; nothing was returned.\n- `processing_error`: The payment could not be processed.\n\n## Idempotency\nSend an `Idempotency-Key` header (a UUID v4) with every POST. It is **required** on\n`POST /v1/payment_intents` and `POST /v1/refunds`. A retry with the same key and body returns\nthe first response (`Idempotent-Replayed: true`), even an error; the same key with a\ndifferent body is refused (409 `idempotency_key_reused`); a retry while the first request is\nstill running gets 409 `idempotency_request_in_progress`. Keys are kept for 48 hours.\nPayments and refunds are never re-sent on your behalf: when a response says `processing` or\n`pending`, wait for the webhook instead of retrying with a new key.\n\n## Rate limits\nPer API key, per minute: live 1500 reads and 300 writes; test\n600 reads and 120 writes. Every response carries\n`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a 429\ncarries `Retry-After`.\n\n## Versioning\nThe major version is in the path (`/v1`). Breaking changes within v1 ship as a new dated\nversion: your key uses the version it was created with; send `ZyloPay-Version: <date>` to\nchoose one per request. Current version: `2026-09-28`. Adding fields, event types,\nerror codes or endpoints is not breaking: ignore what you do not know.\n\n## Webhooks\nRegister endpoints (`POST /v1/webhook_endpoints`); ZyloPay POSTs each event (the same object as\n`GET /v1/events/{id}`) with the header\n`ZyloPay-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>`.\nVerify it on the raw body with your endpoint secret (`whsec_…`), compare in constant time,\nand reject timestamps more than 5 minutes away from your clock (replay\nprotection). During a secret rotation the header carries one `v1` per active secret. Answer\n2xx quickly; anything else (or no answer within 10 s) is retried with exponential backoff for\n3 days. Deliveries are at least once and not ordered: deduplicate on the event `id` and\nre-read objects when order matters. See the `webhooks` section for every event type.","version":"2026-09-28","contact":{"name":"ZyloPay Developer Support","url":"https://zylopay.com/developers","email":"developers@zylopay.com"},"termsOfService":"https://zylopay.com/legal/terms","x-api-versions":["2026-09-28"],"license":{"name":"Proprietary","identifier":"LicenseRef-ZyloPay"}},"tags":[{"name":"Payments","description":"Settled payments (indexed from the chain)."},{"name":"Payment intents","description":"A payment to be taken on one of your terminals, and its lifecycle."},{"name":"Refunds","description":"Return all or part of a payment to the payer."},{"name":"Terminals","description":"Your POS terminals."},{"name":"Balance","description":"Funds held for you in the settlement contract."},{"name":"Events","description":"Everything that happened, as webhooks deliver it (30 days)."},{"name":"Webhooks","description":"Endpoints, signing secrets and the delivery log."}],"servers":[{"url":"https://zylopay-api.fly.dev","description":"Production (live and test mode on one host: the API key chooses)"}],"components":{"securitySchemes":{"ApiKey":{"scheme":"bearer","bearerFormat":"zp_{live|test}_sk_…","type":"http","description":"Secret API key from the dashboard (Developers → API keys)."}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail"}},"required":["error"]},"ApiErrorDetail":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","idempotency_error","rate_limit_error","api_error"],"examples":["invalid_request_error"]},"code":{"type":"string","description":"Stable, machine-readable code (see the error code catalogue).","examples":["parameter_invalid"]},"message":{"type":"string","description":"Human-readable explanation. May change; do not parse it.","examples":["amount must not be less than 1"]},"param":{"type":"string","description":"The parameter (or header) at fault.","examples":["amount"]},"request_id":{"type":"string","description":"The `Request-Id` of the request; quote it to support.","examples":["6f1c2a9e-3b7d-4c55-9a0e-2d4b8f1e7c30"]}},"required":["type","code","message","request_id"]},"Balance":{"type":"object","properties":{"object":{"type":"string","enum":["balance"],"examples":["balance"]},"livemode":{"type":"boolean","examples":[false]},"available":{"description":"Settled funds held for the merchant in the ZyloPay settlement contract, withdrawable to the settlement wallet.","type":"array","items":{"$ref":"#/components/schemas/BalanceAmount"}},"network":{"type":"string","enum":["mainnet","testnet"],"examples":["testnet"]},"as_of":{"type":"string","format":"date-time","description":"When the balance was read from the chain.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["object","livemode","available","network","as_of"]},"BalanceAmount":{"type":"object","properties":{"amount":{"type":"integer","format":"int64","minimum":0,"description":"USDC atoms.","examples":[125000000]},"currency":{"type":"string","enum":["usdc"],"examples":["usdc"]}},"required":["amount","currency"]},"CreatePaymentIntentRequest":{"type":"object","properties":{"amount":{"type":"integer","format":"int64","description":"Amount to charge, in USDC atoms (6 decimals: `2500000` = 2.50 USDC). The payer also pays the network fees on top.","minimum":1,"maximum":1000000000000,"examples":[2500000]},"terminal":{"type":"string","description":"The terminal that takes the payment (`tml_…`, from `GET /v1/terminals`).","examples":["tml_ZP-4821-K"]},"order_id":{"type":"string","description":"Your order reference, 1-8 characters `A-Z a-z 0-9 - _` (it is written on-chain with the settlement and must be unique per account and mode). Generated when omitted.","maxLength":8,"examples":["A7K2Q9XZ"]},"description":{"type":"string","description":"Shown on the terminal while it waits for the tap.","maxLength":500,"examples":["Table 12"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":20,"description":"Up to 20 key/value pairs (keys 1-40 characters of `A-Z a-z 0-9 _ . -`, string values up to 500 characters) returned unchanged. Never store secrets or personal data here.","examples":[{"pos_order":"48213","store":"lisbon-01"}]},"expires_in":{"type":"integer","description":"Seconds until the intent expires if nobody pays it (30-600). After that it is `canceled` with `cancellation_reason: expired`.","minimum":30,"maximum":600,"default":120,"examples":[120]}},"required":["amount","terminal"]},"CreateRefundRequest":{"type":"object","properties":{"payment":{"type":"string","description":"The payment to refund (`pay_…`).","examples":["pay_1042"]},"amount":{"type":"integer","format":"int64","description":"Amount to refund in USDC atoms. Defaults to everything not yet refunded. Partial refunds are allowed until the payment is fully refunded.","minimum":1,"maximum":1000000000000,"examples":[1000000]},"reason":{"type":"string","description":"Why you refund (kept in the refund record).","maxLength":500,"examples":["Customer returned the item"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":20,"description":"Up to 20 key/value pairs (keys 1-40 characters of `A-Z a-z 0-9 _ . -`, string values up to 500 characters) returned unchanged. Never store secrets or personal data here.","examples":[{"pos_order":"48213","store":"lisbon-01"}]}},"required":["payment"]},"CreateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","description":"Where to POST events. `https` is required for live mode (`http` is allowed in test mode). Private, loopback and link-local addresses are refused.","maxLength":2048,"examples":["https://example.com/zylopay/webhooks"]},"enabled_events":{"description":"Event types to receive: exact types, families such as `payment_intent.*`, or `*` for all. Available: `payment.succeeded`, `payment.refunded`, `payment_intent.created`, `payment_intent.requires_action`, `payment_intent.processing`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.canceled`, `refund.created`, `refund.succeeded`, `refund.failed`, `terminal.created`, `terminal.deactivated`, `terminal.deleted`, `kyb.status_changed`.","type":"array","items":{"type":"string"},"examples":[["payment.succeeded","refund.*"]]},"description":{"type":"string","maxLength":500,"examples":["Order service (production)"]},"api_version":{"type":"string","enum":["2026-09-28"],"description":"Version of the event payloads. Defaults to the latest."}},"required":["url","enabled_events"]},"DeletedWebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","examples":["we_2Lk9Qm4Xz7Pv1Rt8Wb3Ns6Hd"]},"object":{"type":"string","enum":["webhook_endpoint"],"examples":["webhook_endpoint"]},"deleted":{"type":"boolean","enum":[true],"examples":[true]}},"required":["id","object","deleted"]},"DeliveryAttempt":{"type":"object","properties":{"attempt":{"type":"integer","examples":[1]},"started_at":{"type":"string","format":"date-time","description":"When the request was sent.","examples":["2026-09-28T14:03:11.402Z"]},"duration_ms":{"type":"integer","examples":[182]},"status_code":{"type":["integer","null"],"examples":[200]},"error":{"type":["string","null"],"examples":[null]},"response_body":{"type":["string","null"],"description":"First 1 KB of your endpoint's response.","examples":["ok"]}},"required":["attempt","started_at","duration_ms","status_code","error","response_body"]},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`evt_…`). Deduplicate webhooks on it.","examples":["evt_7Hq2Zp9LwK4mXr8Vb3Ns1Td5"]},"object":{"type":"string","enum":["event"],"examples":["event"]},"type":{"type":"string","enum":["payment.succeeded","payment.refunded","payment_intent.created","payment_intent.requires_action","payment_intent.processing","payment_intent.succeeded","payment_intent.payment_failed","payment_intent.canceled","refund.created","refund.succeeded","refund.failed","terminal.created","terminal.deactivated","terminal.deleted","kyb.status_changed","ping"],"examples":["payment.succeeded"]},"api_version":{"type":"string","enum":["2026-09-28"],"examples":["2026-09-28"]},"livemode":{"type":"boolean","examples":[false]},"created":{"type":"string","format":"date-time","description":"When the change happened.","examples":["2026-09-28T14:03:11.402Z"]},"data":{"$ref":"#/components/schemas/EventData"}},"required":["id","object","type","api_version","livemode","created","data"]},"EventData":{"type":"object","properties":{"object":{"type":"object","additionalProperties":true,"description":"The object the event is about, as it was at that moment (`payment`, `payment_intent`, `refund`, `terminal`, `kyb_verification` or `webhook_endpoint`; see the event type)."},"previous_attributes":{"type":"object","additionalProperties":true,"description":"For `*.refunded` / `kyb.status_changed`: the changed fields' previous values."}},"required":["object"]},"EventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Events of the last 30 days, newest first.","type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"KybVerification":{"type":"object","required":["object","livemode","status","live_payments_enabled","updated"],"properties":{"object":{"type":"string","enum":["kyb_verification"]},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["not_started","pending","approved","rejected","needs_info"]},"live_payments_enabled":{"type":"boolean","description":"True when live payments are allowed (`approved`)."},"updated":{"type":"string","format":"date-time"}}},"NextAction":{"type":"object","properties":{"type":{"type":"string","enum":["payer_confirmation"],"description":"The payer must confirm the payment in the ZyloPay app.","examples":["payer_confirmation"]},"reason_code":{"type":["string","null"],"enum":["AMOUNT_ABOVE_THRESHOLD","RISK_FLAGGED","FIRST_MERCHANT_PAYMENT","CUMULATIVE_LIMIT",null],"description":"Why confirmation is needed.","examples":["AMOUNT_ABOVE_THRESHOLD"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"The confirmation request expires at this time.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["type","reason_code","expires_at"]},"Payment":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`pay_…`).","examples":["pay_1042"]},"object":{"type":"string","enum":["payment"],"examples":["payment"]},"livemode":{"type":"boolean","description":"`true` on mainnet (live key), `false` on testnet (test key).","examples":[false]},"amount":{"type":"integer","format":"int64","minimum":0,"description":"Amount charged for the sale, in USDC atoms (6 decimals). The merchant receives all of it.","examples":[2500000]},"currency":{"type":"string","enum":["usdc"],"examples":["usdc"]},"amount_refunded":{"type":"integer","format":"int64","minimum":0,"description":"Amount refunded so far (USDC atoms).","examples":[0]},"status":{"type":"string","enum":["succeeded","partially_refunded","refunded"],"examples":["succeeded"]},"fees":{"$ref":"#/components/schemas/PaymentFees"},"total_charged":{"type":"integer","format":"int64","minimum":0,"description":"What was pulled from the payer (`amount` + fees − instant cashback).","examples":[2512500]},"net":{"type":"integer","format":"int64","minimum":0,"description":"What the merchant received (USDC atoms). Equals `amount`.","examples":[2500000]},"cashback_status":{"type":"string","enum":["paid","accrued","none"],"description":"`paid`: cashback paid to the payer in the settlement itself; `accrued`: credited for a later claim (older contract); `none`.","examples":["paid"]},"payer":{"type":"string","description":"Payer wallet address (lowercase).","examples":["0x8ba1f109551bd432803012645ac136ddd64dba72"]},"order_id":{"type":"string","description":"Order ID written on-chain with the settlement.","examples":["A7K2Q9XZ"]},"terminal":{"type":["string","null"],"description":"Terminal that took the payment (`tml_…`).","examples":["tml_ZP-4821-K"]},"payment_intent":{"type":["string","null"],"description":"The payment intent (`pi_…`) this payment settled.","examples":["pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60"]},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"split_group":{"type":["string","null"],"description":"Split-payment group, when the sale was split across payers.","examples":[null]},"network":{"type":"string","enum":["mainnet","testnet"],"examples":["testnet"]},"chain_id":{"type":"integer","enum":[143,10143],"description":"Monad chain ID.","examples":[10143]},"tx_hash":{"type":["string","null"],"description":"Settlement transaction hash on Monad.","examples":["0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"]},"block_number":{"type":["integer","null"],"examples":[48213377]},"log_index":{"type":["integer","null"],"examples":[3]},"settled_at":{"type":["string","null"],"format":"date-time","description":"Block time of the settlement.","examples":["2026-09-28T14:03:11.402Z"]},"created":{"type":"string","format":"date-time","description":"When ZyloPay indexed the settlement.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["id","object","livemode","amount","currency","amount_refunded","status","fees","total_charged","net","cashback_status","payer","order_id","terminal","payment_intent","payment_method","split_group","network","chain_id","tx_hash","block_number","log_index","settled_at","created"]},"PaymentError":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable reason (see the payment error codes in the API reference).","examples":["pass_frozen"]},"message":{"type":"string","examples":["This wallet pass is frozen. Ask the customer to pay with another pass."]}},"required":["code","message"]},"PaymentFees":{"type":"object","properties":{"acquirer":{"type":"integer","format":"int64","minimum":0,"description":"POS acquirer fee (USDC atoms), paid by the payer on top of `amount`.","examples":[6250]},"protocol":{"type":"integer","format":"int64","minimum":0,"description":"ZyloPay protocol fee (USDC atoms), paid by the payer on top of `amount`.","examples":[6250]},"cashback":{"type":"integer","format":"int64","minimum":0,"description":"Payer cashback funded from the fees (USDC atoms).","examples":[1250]}},"required":["acquirer","protocol","cashback"]},"PaymentIntent":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`pi_…`).","examples":["pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60"]},"object":{"type":"string","enum":["payment_intent"],"examples":["payment_intent"]},"livemode":{"type":"boolean","examples":[false]},"amount":{"type":"integer","format":"int64","minimum":0,"description":"Amount to charge (USDC atoms).","examples":[2500000]},"currency":{"type":"string","enum":["usdc"],"examples":["usdc"]},"status":{"type":"string","enum":["requires_payment_method","requires_action","processing","succeeded","canceled"],"description":"`requires_payment_method`: waiting for a tap (again, after a failed attempt). `requires_action`: held for payer confirmation (`next_action`). `processing`: settlement sent, outcome pending — never retry. `succeeded`: settled (`payment` once indexed). `canceled`: nothing was or will be charged.","examples":["requires_payment_method"]},"terminal":{"type":"string","description":"Terminal that takes the payment (`tml_…`).","examples":["tml_ZP-4821-K"]},"order_id":{"type":"string","examples":["A7K2Q9XZ"]},"description":{"type":["string","null"],"examples":["Table 12"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"examples":[{"pos_order":"48213"}]},"source":{"type":"string","enum":["api","terminal"],"description":"Created by your server (`api`) or by the POS (`terminal`).","examples":["api"]},"payment":{"type":["string","null"],"description":"The settled payment (`pay_…`), once indexed.","examples":[null]},"tx_hash":{"type":["string","null"],"description":"Settlement transaction hash, once sent.","examples":[null]},"next_action":{"oneOf":[{"$ref":"#/components/schemas/NextAction"},{"type":"null"}]},"last_payment_error":{"description":"Why the last attempt failed. Cleared on success.","oneOf":[{"$ref":"#/components/schemas/PaymentError"},{"type":"null"}]},"cancellation_reason":{"type":["string","null"],"enum":["requested_by_merchant","canceled_at_terminal","expired","step_up_denied","step_up_expired",null],"examples":[null]},"canceled_at":{"type":["string","null"],"format":"date-time","description":"When the intent was canceled.","examples":["2026-09-28T14:03:11.402Z"]},"network":{"type":"string","enum":["mainnet","testnet"],"examples":["testnet"]},"expires_at":{"type":"string","format":"date-time","description":"The intent can no longer be paid after this time.","examples":["2026-09-28T14:03:11.402Z"]},"created":{"type":"string","format":"date-time","description":"Creation time.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["id","object","livemode","amount","currency","status","terminal","order_id","description","metadata","source","payment","tx_hash","next_action","last_payment_error","cancellation_reason","canceled_at","network","expires_at","created"]},"PaymentIntentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Payment intents, newest first.","type":"array","items":{"$ref":"#/components/schemas/PaymentIntent"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"PaymentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Payments, newest first.","type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"PaymentMethod":{"type":"object","properties":{"type":{"type":"string","enum":["wallet_pass"],"examples":["wallet_pass"]},"credential":{"type":["string","null"],"enum":["nfc_id","payment_token",null],"description":"Which pass credential the terminal read: the Smart Tap / VAS NFC ID, or a rotating payment token (QR). Null when the payment was not made through the relay.","examples":["nfc_id"]}},"required":["type","credential"]},"Refund":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`re_…`).","examples":["re_4Fq9LwP2mZt8Xk3Vb7Ns1Hdq"]},"object":{"type":"string","enum":["refund"],"examples":["refund"]},"livemode":{"type":"boolean","examples":[false]},"amount":{"type":"integer","format":"int64","minimum":0,"description":"Amount refunded (USDC atoms).","examples":[1000000]},"currency":{"type":"string","enum":["usdc"],"examples":["usdc"]},"payment":{"type":"string","description":"The refunded payment (`pay_…`).","examples":["pay_1042"]},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: sent, confirmation not seen yet (resolves automatically; do not retry). `succeeded`: funds returned. `failed`: nothing moved (`failure_code`).","examples":["succeeded"]},"reason":{"type":["string","null"],"examples":["Customer returned the item"]},"failure_code":{"type":["string","null"],"enum":["refund_failed","settlement_reverted",null],"examples":[null]},"failure_message":{"type":["string","null"],"examples":[null]},"tx_hash":{"type":["string","null"],"description":"Refund transaction hash on Monad.","examples":["0x9e1f0c8a36f2a7b6d1e4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d"]},"source":{"type":"string","enum":["api","dashboard","pos","admin"],"description":"Where the refund was requested: your API key, your dashboard, a terminal, or ZyloPay support (admin, under dual control).","examples":["api"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"examples":[{}]},"network":{"type":"string","enum":["mainnet","testnet"],"examples":["testnet"]},"created":{"type":"string","format":"date-time","description":"Creation time.","examples":["2026-09-28T14:03:11.402Z"]},"updated":{"type":"string","format":"date-time","description":"Last status change.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["id","object","livemode","amount","currency","payment","status","reason","failure_code","failure_message","tx_hash","source","metadata","network","created","updated"]},"RefundList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Refunds, newest first.","type":"array","items":{"$ref":"#/components/schemas/Refund"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"RotateWebhookSecretRequest":{"type":"object","properties":{"expires_in_hours":{"type":"integer","description":"How long the previous secret keeps signing deliveries alongside the new one (0-168 hours). `0` stops it at once.","minimum":0,"maximum":168,"default":24,"examples":[24]}}},"Terminal":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`tml_…`).","examples":["tml_ZP-4821-K"]},"object":{"type":"string","enum":["terminal"],"examples":["terminal"]},"livemode":{"type":"boolean","examples":[false]},"label":{"type":"string","description":"The terminal ID shown on the device.","examples":["ZP-4821-K"]},"name":{"type":"string","examples":["Counter 1"]},"platform":{"type":"string","examples":["generic"]},"status":{"type":"string","enum":["active","inactive"],"examples":["active"]},"last_seen_at":{"type":["string","null"],"format":"date-time","description":"Last time the terminal called ZyloPay.","examples":["2026-09-28T14:03:11.402Z"]},"network":{"type":"string","enum":["mainnet","testnet"],"examples":["testnet"]},"created":{"type":"string","format":"date-time","description":"Provisioning time.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["id","object","livemode","label","name","platform","status","last_seen_at","network","created"]},"TerminalList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Terminals, newest first.","type":"array","items":{"$ref":"#/components/schemas/Terminal"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"UpdateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"examples":["https://example.com/zylopay/webhooks"]},"enabled_events":{"description":"Event types to receive: exact types, families such as `payment_intent.*`, or `*` for all. Available: `payment.succeeded`, `payment.refunded`, `payment_intent.created`, `payment_intent.requires_action`, `payment_intent.processing`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.canceled`, `refund.created`, `refund.succeeded`, `refund.failed`, `terminal.created`, `terminal.deactivated`, `terminal.deleted`, `kyb.status_changed`.","type":"array","items":{"type":"string"},"examples":[["*"]]},"description":{"type":"string","maxLength":500},"disabled":{"type":"boolean","description":"`true` stops deliveries (events are kept and delivered when re-enabled, within 3 days); `false` re-enables and resets the failure window."}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`wdl_…`).","examples":["wdl_8Tq3Zm1Xk6Pv9Rw2Lb4Ns7Hd"]},"object":{"type":"string","enum":["webhook_delivery"],"examples":["webhook_delivery"]},"livemode":{"type":"boolean","examples":[false]},"endpoint":{"type":"string","examples":["we_2Lk9Qm4Xz7Pv1Rt8Wb3Ns6Hd"]},"event":{"type":"string","examples":["evt_7Hq2Zp9LwK4mXr8Vb3Ns1Td5"]},"event_type":{"type":["string","null"],"examples":["payment.succeeded"]},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for the next attempt. `failed`: gave up after 3 days (or a single manual attempt failed).","examples":["succeeded"]},"attempts":{"type":"integer","examples":[1]},"manual":{"type":"boolean","description":"A resend or test event (one attempt, not retried).","examples":[false]},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Next automatic attempt (pending only).","examples":["2026-09-28T14:03:11.402Z"]},"last_attempt_at":{"type":["string","null"],"format":"date-time","description":"Last attempt.","examples":["2026-09-28T14:03:11.402Z"]},"last_status_code":{"type":["integer","null"],"examples":[200]},"last_error":{"type":["string","null"],"examples":[null]},"created":{"type":"string","format":"date-time","description":"Creation time (the event's fan-out).","examples":["2026-09-28T14:03:11.402Z"]},"completed_at":{"type":["string","null"],"format":"date-time","description":"When it succeeded or was given up.","examples":["2026-09-28T14:03:11.402Z"]},"attempt_log":{"description":"Every attempt (retrieve only).","type":"array","items":{"$ref":"#/components/schemas/DeliveryAttempt"}}},"required":["id","object","livemode","endpoint","event","event_type","status","attempts","manual","next_attempt_at","last_attempt_at","last_status_code","last_error","created","completed_at"]},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"Deliveries to the endpoint, newest first.","type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (`we_…`).","examples":["we_2Lk9Qm4Xz7Pv1Rt8Wb3Ns6Hd"]},"object":{"type":"string","enum":["webhook_endpoint"],"examples":["webhook_endpoint"]},"livemode":{"type":"boolean","examples":[false]},"url":{"type":"string","examples":["https://example.com/zylopay/webhooks"]},"description":{"type":["string","null"],"examples":["Order service (production)"]},"enabled_events":{"description":"`[\"*\"]` or the subscribed event types.","type":"array","items":{"type":"string"},"examples":[["payment.succeeded","refund.failed","refund.succeeded"]]},"status":{"type":"string","enum":["enabled","disabled"],"examples":["enabled"]},"disabled_reason":{"type":["string","null"],"enum":["merchant","failing",null],"description":"`failing`: disabled automatically after failing for 3 days.","examples":[null]},"api_version":{"type":"string","enum":["2026-09-28"],"examples":["2026-09-28"]},"failing_since":{"type":["string","null"],"format":"date-time","description":"First failure since the last successful delivery (null while healthy).","examples":["2026-09-28T14:03:11.402Z"]},"last_success_at":{"type":["string","null"],"format":"date-time","description":"Last successful delivery.","examples":["2026-09-28T14:03:11.402Z"]},"secret_rotation_ends_at":{"type":["string","null"],"format":"date-time","description":"While set, deliveries are also signed with the previous secret (rotation overlap).","examples":["2026-09-28T14:03:11.402Z"]},"secret":{"type":"string","description":"Signing secret (`whsec_…`). Returned ONLY when the endpoint is created or its secret rotated: store it now.","examples":["whsec_Zx3Kq9Lm2Pw7Rv4Tb8Ns1Hd6Fg5Jc0Ya9Ue2Io3Qp4"]},"created":{"type":"string","format":"date-time","description":"Creation time.","examples":["2026-09-28T14:03:11.402Z"]},"updated":{"type":"string","format":"date-time","description":"Last change.","examples":["2026-09-28T14:03:11.402Z"]}},"required":["id","object","livemode","url","description","enabled_events","status","disabled_reason","api_version","failing_since","last_success_at","secret_rotation_ends_at","created","updated"]},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"examples":["list"]},"data":{"description":"All webhook endpoints of this mode.","type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean","description":"More (older) objects exist.","examples":[false]},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page.","examples":[null]}},"required":["object","data","has_more","next_cursor"]}},"headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window for this key.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Request-Id":{"description":"Unique ID of this request, also sent as X-Request-Id (quote it to support). You may send your own plain X-Request-Id (8-128 chars of A-Z a-z 0-9 . _ : -).","schema":{"type":"string","examples":["6f1c2a9e-3b7d-4c55-9a0e-2d4b8f1e7c30"]}},"ZyloPay-Version":{"description":"API version used to render the response.","schema":{"type":"string","enum":["2026-09-28"]}}}},"jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","webhooks":{"kyb.status_changed":{"post":{"operationId":"webhook_kyb_status_changed","summary":"kyb.status_changed","description":"The business verification status changed (for example `pending` → `approved`). Sent in both modes.\n\n`data.object` is a `kyb_verification`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["kyb.status_changed"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["kyb.status_changed"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/KybVerification"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment.refunded":{"post":{"operationId":"webhook_payment_refunded","summary":"payment.refunded","description":"A refund of the payment succeeded; `amount_refunded` and `status` changed (`previous_attributes`).\n\n`data.object` is a `payment`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment.refunded"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment.refunded"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Payment"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment.succeeded":{"post":{"operationId":"webhook_payment_succeeded","summary":"payment.succeeded","description":"A payment settled on-chain and was indexed. Fires once per payment, whatever created it (terminal or API).\n\n`data.object` is a `payment`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment.succeeded"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment.succeeded"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Payment"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.canceled":{"post":{"operationId":"webhook_payment_intent_canceled","summary":"payment_intent.canceled","description":"The payment intent was canceled (by you, the cashier, the payer declining the confirmation, or expiry). Nothing was charged.\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.canceled"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.canceled"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.created":{"post":{"operationId":"webhook_payment_intent_created","summary":"payment_intent.created","description":"A payment intent was created through the API for a terminal.\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.created"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.created"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.payment_failed":{"post":{"operationId":"webhook_payment_intent_payment_failed","summary":"payment_intent.payment_failed","description":"A payment attempt was declined or failed; nothing was charged. `last_payment_error` says why. The intent can be retried until it expires.\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.payment_failed"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.payment_failed"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.processing":{"post":{"operationId":"webhook_payment_intent_processing","summary":"payment_intent.processing","description":"The settlement was broadcast but its outcome is not known yet. Never retry: ZyloPay resolves it and sends `payment_intent.succeeded` or `payment_intent.payment_failed`.\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.processing"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.processing"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.requires_action":{"post":{"operationId":"webhook_payment_intent_requires_action","summary":"payment_intent.requires_action","description":"The payment is held until the payer confirms it in the ZyloPay app (step-up). `next_action` says why and until when.\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.requires_action"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.requires_action"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"payment_intent.succeeded":{"post":{"operationId":"webhook_payment_intent_succeeded","summary":"payment_intent.succeeded","description":"The payment settled. `payment` names the settled payment once indexed (see `payment.succeeded`).\n\n`data.object` is a `payment_intent`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["payment_intent.succeeded"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["payment_intent.succeeded"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/PaymentIntent"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"ping":{"post":{"operationId":"webhook_ping","summary":"ping","description":"A test event sent from the dashboard or `POST /v1/webhook_endpoints/{id}/test`.\n\n`data.object` is a `webhook_endpoint`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["ping"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["ping"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"refund.created":{"post":{"operationId":"webhook_refund_created","summary":"refund.created","description":"A refund was created and sent (status `pending`).\n\n`data.object` is a `refund`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["refund.created"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["refund.created"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Refund"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"refund.failed":{"post":{"operationId":"webhook_refund_failed","summary":"refund.failed","description":"The refund did not happen (nothing moved). `failure_code` says why.\n\n`data.object` is a `refund`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["refund.failed"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["refund.failed"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Refund"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"refund.succeeded":{"post":{"operationId":"webhook_refund_succeeded","summary":"refund.succeeded","description":"The refund was mined; the funds are back with the payer.\n\n`data.object` is a `refund`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["refund.succeeded"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["refund.succeeded"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Refund"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"terminal.created":{"post":{"operationId":"webhook_terminal_created","summary":"terminal.created","description":"A terminal was provisioned.\n\n`data.object` is a `terminal`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["terminal.created"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["terminal.created"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Terminal"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"terminal.deactivated":{"post":{"operationId":"webhook_terminal_deactivated","summary":"terminal.deactivated","description":"A terminal was deactivated; its key stops working.\n\n`data.object` is a `terminal`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["terminal.deactivated"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["terminal.deactivated"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Terminal"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}},"terminal.deleted":{"post":{"operationId":"webhook_terminal_deleted","summary":"terminal.deleted","description":"A deactivated terminal was deleted.\n\n`data.object` is a `terminal`. Signed with `ZyloPay-Signature`.","parameters":[{"name":"ZyloPay-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` (one `v1` per active secret).","schema":{"type":"string"}},{"name":"ZyloPay-Event-Id","in":"header","required":true,"description":"The event ID; deduplicate on it.","schema":{"type":"string"}},{"name":"ZyloPay-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["terminal.deleted"]}},{"name":"ZyloPay-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"ZyloPay-Delivery-Attempt","in":"header","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"type":"string","enum":["terminal.deleted"]},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Terminal"}}}}}]}}}},"responses":{"2XX":{"description":"Received. Any other answer (or none within 10 s) is retried."}}}}},"x-error-codes":{"account_disabled":{"type":"permission_error","status":403,"description":"The merchant account is disabled. Read-only requests still work. Contact ZyloPay support."},"account_not_live":{"type":"invalid_request_error","status":409,"description":"The merchant is not registered on this network yet (go live from the dashboard first)."},"account_restricted":{"type":"permission_error","status":403,"description":"An account involved in this action cannot be used with ZyloPay right now. Nothing was done. Contact ZyloPay support."},"amount_too_large":{"type":"invalid_request_error","status":400,"description":"The amount exceeds what is allowed (for a refund: the amount still refundable)."},"api_key_expired":{"type":"authentication_error","status":401,"description":"The API key has passed its expiry (for example the overlap window of a rotation ended)."},"api_key_invalid":{"type":"authentication_error","status":401,"description":"The API key is malformed or unknown."},"api_key_missing":{"type":"authentication_error","status":401,"description":"No API key was sent. Send `Authorization: Bearer <secret key>`."},"api_key_revoked":{"type":"authentication_error","status":401,"description":"The API key was revoked."},"api_version_invalid":{"type":"invalid_request_error","status":400,"description":"The `ZyloPay-Version` header names a version that does not exist."},"cursor_invalid":{"type":"invalid_request_error","status":400,"description":"The pagination cursor is malformed or belongs to another list."},"idempotency_key_invalid":{"type":"idempotency_error","status":400,"description":"The `Idempotency-Key` must be 1-255 printable ASCII characters."},"idempotency_key_required":{"type":"idempotency_error","status":400,"description":"This endpoint moves money and requires an `Idempotency-Key` header."},"idempotency_key_reused":{"type":"idempotency_error","status":409,"description":"The `Idempotency-Key` was already used with a different request (method, path or body)."},"idempotency_request_in_progress":{"type":"idempotency_error","status":409,"description":"A request with this `Idempotency-Key` is still being processed (or was interrupted). Do not retry with a new key before checking the outcome."},"insufficient_scope":{"type":"permission_error","status":403,"description":"The API key lacks the scope this endpoint requires (see `required_scope` in the message)."},"internal_error":{"type":"api_error","status":500,"description":"Something went wrong on ZyloPay's side. A retry with the same `Idempotency-Key` replays this error: check the object, then retry with a new key only if nothing happened."},"ip_not_allowed":{"type":"permission_error","status":403,"description":"The request IP is not in the API key's IP allowlist."},"kyb_required":{"type":"permission_error","status":403,"description":"Live mode needs an approved business verification (KYB) for this action."},"network_mismatch":{"type":"invalid_request_error","status":400,"description":"An `X-Network` header was sent that contradicts the API key's mode. API keys choose the network; omit the header."},"parameter_invalid":{"type":"invalid_request_error","status":400,"description":"A parameter has an invalid value (see `param`)."},"parameter_missing":{"type":"invalid_request_error","status":400,"description":"A required parameter is missing (see `param`)."},"parameter_unknown":{"type":"invalid_request_error","status":400,"description":"The request contains a parameter the endpoint does not accept (see `param`)."},"payment_already_refunded":{"type":"invalid_request_error","status":409,"description":"The payment has already been fully refunded."},"payment_intent_unexpected_state":{"type":"invalid_request_error","status":409,"description":"The payment intent is not in a state that allows this action (see `message`)."},"publishable_key_not_allowed":{"type":"permission_error","status":403,"description":"Publishable keys cannot call this endpoint; use a secret key from your server."},"rate_limited":{"type":"rate_limit_error","status":429,"description":"Too many requests for this API key. Wait for `Retry-After` seconds."},"refund_daily_limit_reached":{"type":"invalid_request_error","status":409,"description":"The account's daily refund limit would be exceeded."},"refund_in_progress":{"type":"invalid_request_error","status":409,"description":"Another refund of this payment is being sent; retry after it completes."},"refund_window_expired":{"type":"invalid_request_error","status":409,"description":"The payment is older than the refund window of the account."},"request_timeout":{"type":"api_error","status":503,"description":"The request exceeded its time budget and keeps running. Retry with the same `Idempotency-Key` (it never runs twice): you get its real outcome once it finished, `idempotency_request_in_progress` until then."},"resource_missing":{"type":"invalid_request_error","status":404,"description":"No such object for this account and mode."},"service_unavailable":{"type":"api_error","status":503,"description":"A dependency is temporarily unavailable. A retry with the same `Idempotency-Key` replays this error: check the object, then retry later with a new key only if nothing happened."},"terminal_inactive":{"type":"invalid_request_error","status":409,"description":"The terminal is deactivated."},"webhook_endpoint_disabled":{"type":"invalid_request_error","status":409,"description":"The webhook endpoint is disabled; enable it first."},"webhook_endpoint_limit_reached":{"type":"invalid_request_error","status":400,"description":"The account has the maximum number of webhook endpoints for this mode."},"webhook_url_forbidden":{"type":"invalid_request_error","status":400,"description":"The URL resolves to a private, loopback, link-local or otherwise reserved address."},"webhook_url_invalid":{"type":"invalid_request_error","status":400,"description":"The URL is not a valid absolute http(s) URL, uses http in live mode, or carries credentials."}},"x-payment-error-codes":{"pass_revoked":"The wallet pass was revoked.","pass_frozen":"The wallet pass is frozen.","pass_wrong_network":"The wallet pass was issued for the other network.","authorization_required":"The wallet pass has no payment authorization; the payer must re-create it.","authorization_expired":"The payer's spending approval expired; the payer must renew the pass.","amount_exceeds_approval":"The amount is above the payer's spending approval.","payer_frozen":"The payer's account is frozen.","terminal_daily_limit":"The terminal reached its daily volume cap.","risk_declined":"The payment was declined by risk rules.","step_up_denied":"The payer or the cashier declined the confirmation request.","step_up_expired":"The payer did not confirm in time.","session_invalid":"The payment session was invalid, expired or already used.","order_already_paid":"Another payment of this `order_id` is settled or in progress; nothing was charged by this attempt. Check that payment before charging again.","credential_invalid":"The pass credential presented at the terminal is unknown or invalid.","merchant_disabled":"The merchant account is disabled.","kyb_required":"Live payments need an approved business verification.","account_restricted":"The payer's account cannot be used with ZyloPay right now. Nothing was charged.","settlement_failed":"The on-chain settlement failed; nothing was charged.","settlement_reverted":"The on-chain transaction reverted; nothing was charged.","refund_failed":"The on-chain refund failed; nothing was returned.","processing_error":"The payment could not be processed."},"x-scopes":{"payments:read":"List and retrieve payments and payment intents.","payments:write":"Create and cancel payment intents on your terminals.","refunds:read":"List and retrieve refunds.","refunds:write":"Create refunds.","terminals:read":"List and retrieve terminals.","balance:read":"Read the account balance.","events:read":"List and retrieve events.","webhooks:read":"List webhook endpoints and their delivery logs.","webhooks:manage":"Create, update, delete webhook endpoints, rotate secrets, resend and send test events."}}