{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"pstrykk API","version":"1.2.0","summary":"Merchant payments, subscriptions, refunds, balances, and QR generation.","description":"pstrykk API v1\n\nScope and compatibility\nThis document describes only the HTTP routes implemented by the supplied pstrykk API service. There is no payment-list route, merchant webhook registration, card-data submission, manual capture, merchant onboarding, or sandbox switch in this API. Examples contain illustrative data, not live credentials or executed transactions.\n\nBase URL\nSend all API requests to https://api.pstrykk.pl, using the /v1 endpoints documented below. Example: POST https://api.pstrykk.pl/v1/payments. The pay.pstrykk.pl and embedded.pstrykk.pl domains serve checkout pages, not API endpoints. The checkout links returned in paymentUrl use https://pay.pstrykk.pl.\n\nEmbedded checkout (iframe)\nTo embed checkout on your website, replace pay.pstrykk.pl with embedded.pstrykk.pl in paymentUrl, keeping the path and query unchanged. Return buttons and automatic return to the store are disabled in embedded checkout, regardless of redirectWebsite and redirectTime. Receive transaction webhooks on your backend and implement storefront status updates and page refresh based on that backend state; webhooks do not directly refresh the browser.\n\nAuthentication\nEvery endpoint except GET /v1/docs and GET /v1/openapi requires BOTH email and secret HTTP headers, exactly once each. email is trimmed and lowercased, must be nonblank, and cannot exceed 254 characters before trimming. secret is an opaque, nonempty string of at most 1024 characters; it is not trimmed. Send the original secret, not its hash, without a Bearer prefix. Repeated credential headers are rejected. Invalid credentials return HTTP 401. Credential changes take effect on the next request. Never embed credentials in browser code, checkout URLs, or shared examples. This service does not implement CORS responses or an OPTIONS preflight handler; use a trusted server-side integration.\n\nRequest and response conventions\nJSON request bodies must be objects, not arrays, primitives, or null, and may contain at most 65,536 received bytes. An empty body is parsed as {}. Send Content-Type: application/json. Unknown top-level body fields are ignored; unknown paymentMethods codes are rejected. JSON responses use application/json; charset=utf-8. All generated responses use Cache-Control: no-store and X-Content-Type-Options: nosniff. Money fields are integer minor units: 100 = 1.00 PLN or EUR, never a floating-point amount. Request amounts must be JavaScript-safe positive integers. Payment creation accepts only PLN and EUR; payouts and transfer QR codes use PLN. Returned timestamps are normally UTC ISO 8601 strings or null. A status-history timestamp can retain its original stored value if conversion fails.\n\nPayment creation and duplicate prevention\nPOST /v1/payments requires a client-generated UUID v4 requestKey. The key is scoped to the authenticated merchant and stored as submitted; keep its exact spelling on retries. A completed replay returns the same payment with HTTP 201, not HTTP 200, and can reflect its current stored status. Replay still requires the account payment configuration to pass current validation. Conflicting payment data or a rejected requestKey return HTTP 409. New payment creation and replays of tracked unfinished creation return HTTP 202 with the same local payment ID; ready replays return HTTP 201. Older unresolved reservations without a background creation job may still return HTTP 409 during legacy recovery. A rejected requestKey cannot be reused for a new attempt. If a response identifies an uncertain payment, retain id, read GET /v1/payments/{id}, and use POST /v1/payments/{id}/sync to reconcile it. Do not generate a new requestKey merely because a network timeout occurred. Explicit expiry or method flags are compared when supplied; omitting them on a replay reuses stored values rather than comparing against newly calculated defaults.\n\nRefunds and payouts\nRefund requestKey is duplicate-submission protection, not response replay: submitting it again returns HTTP 409 with refundId when the duplicate is detected. Unconfirmed refunds block further operations; do not retry with a different key, and contact support. Payouts have no requestKey or idempotency mechanism. Do not automatically retry a payout after a timeout or an unconfirmed result. Check the balance and reconcile the outcome first. A successful refund or payout response confirms request acceptance, not final bank settlement.\n\nStatuses, polling, and links\nstatus and statusId are service-supplied values, not a fixed enum or a documented numeric lookup table. Do not invent statusId mappings. Recognized normalized status names include Created, Initialized, Opened, Pending, Authorized, Settled, Partially refunded, Refunded, Declined, Disputed, and Chargeback accepted; the original spelling is preserved. Normalize by lowercasing and removing nonalphanumeric characters when comparing these names. For confirmed records it may return stored data if refresh fails; no freshness timestamp is exposed. Use POST sync when a current payment-service read is required. statusHistory is the locally stored history in insertion order, can be empty or incomplete, and need not end with the current status. paymentUrl remains present even for an inactive link. Use linkActive for local link availability, not as evidence that a payment is settled. Payment creation is asynchronous: HTTP 202 returns a locally reserved payment ID and paymentUrl while checkout preparation continues in the background. When creationState is pending, linkActive=false is expected and does not mean that the payment was cancelled. Read GET /v1/payments/{id} to check readiness; linkActive can become true once creationState is ready, provided the link has not expired or been deactivated and the payment status still permits payment. Link deactivation is local and is not a refund or remote cancellation.\n\nErrors and retry safety\nErrors are JSON objects with error and, where relevant, id, refundId, availableCents, payoutGate. Messages may include sanitized additional detail and are not stable machine-readable error codes. A malformed URL may return HTTP 400. Unknown nonpublic routes require authentication and return HTTP 404. A known route with a wrong method returns HTTP 405 and an Allow header. Do not assume every 5xx means a financial operation was not submitted.\n\nSubscriptions (recurring card payments)\nPOST /v1/subscriptions starts a plan in two stages. First, a regular checkout link is prepared for the first payment (amountCents), identified by transactionId; only card methods enabled for the account are offered, because the card is stored for later charges. After the first payment is paid, the payment service activates the plan automatically: recurringAmountCents every monthsFrequency months from startingDate, totalPayments times, without further payer interaction. Recurring charges are not exposed as separate /v1/payments resources; track them with paymentsMade, lastChargeDate, and nextChargeDate from GET /v1/subscriptions. The first payment is an ordinary payment: read, sync, refund, or deactivate it via /v1/payments/{transactionId}; it also produces regular transaction webhooks. There are no subscription-specific webhook events. Plan status is null until the first payment is paid and linked; afterwards it is synchronized in the background and is not a fixed enum. DELETE /v1/subscriptions/{id} stops future charges; it refunds nothing. Creation, replay, and requestKey rules follow POST /v1/payments, and requestKey values are shared between both routes.\n\nWebhooks \u2014 merchant notifications (supplement)\nThis supplementary section describes the outgoing webhook implementation in server and its authenticated panel test endpoint. It does not add webhook registration to /v1. Existing /v1 API routes and their authentication remain unchanged. The formal OpenAPI 3.1 definitions for outgoing deliveries are in the top-level webhooks object. The current built-in HTML renderer only lists paths, so this overview also contains the integration contract.\n\nConfiguration\nIn the merchant panel, open Integrations and API, enter your own public HTTPS webhook URL and a separate webhook secret, then save. The webhook secret is 16\u2013256 printable ASCII characters without spaces and is independent of the API secret. Leaving the secret field empty on save preserves the current secret. Clearing the URL disables notifications. URL credentials and fragments are not allowed. Delivery rejects nonpublic/local IP addresses, including addresses returned by DNS, and does not follow redirects. The current saved URL and secret are used when each delivery attempt runs, including retries; changing them affects queued attempts.\n\nTypes and payloads\nAll three event types are POST requests to the same configured URL, with Content-Type: application/json; charset=utf-8. The JSON envelope is {id,type,createdAt,data}. id is the delivery/event identifier, type is exactly test, transaction, or refund, and createdAt is the event creation time. data depends on type.\n- test: data = {message}; message is the string \"Testowy webhook pstrykk.\". This verifies connectivity and does not create a transaction or refund.\n- transaction: data = {transactionId,requestKey,title,amountCents,currency,statusId,status,paymentDate,cancelledAt}. transactionId is the local pstrykk payment ID, not an upstream identifier. requestKey is the original payment request key, or null for imported/legacy data. Monetary amounts use integer minor units. statusId/status preserve the stored payment-service values without a fixed numeric mapping. Nullable fields are returned as null rather than omitted. cancelledAt indicates local checkout-link deactivation and does not imply a remote cancellation or refund. paymentDate is the stored payment-service value, not a guaranteed normalized timestamp.\n- refund: data = {refundId,transactionId,amountCents,currency,status}. refundId is the local refund-action UUID and transactionId identifies its payment. status is pending (locally reserved), accepted (request accepted, not final settlement), rejected (request rejected), or unknown (outcome unconfirmed; do not resubmit with a new key). This field is named status in webhook payloads, whereas the existing synchronous refund response uses state. Final full/partial refund payment statuses arrive separately as transaction events when recorded locally. These payment status strings retain their original service spelling; normalize if needed rather than assuming fixed text.\n\nWhen events are created\nA transaction event is queued when the stored statusId or status changes, or cancelledAt changes, provided the new row has a non-null status or cancellation timestamp. There is no allowlist of payment statuses. Repeated synchronization with an unchanged status does not create another event. Updates from the upstream webhook, explicit synchronization, and panel imports are covered by database triggers. The first non-null status discovered for an imported payment may create an event. A refund event is queued when a local refund action is inserted and when its state changes; release/preauthorization-cancellation actions do not create refund events. Only events recorded after installation while a URL and secret are configured are queued. No historical backfill, creationState notifications, expiry timer events, or guarantee of every intermediate upstream state is provided. Externally initiated refunds without a local refund action do not receive an invented refundId; their observed payment-status changes can produce transaction events.\n\nSignature and headers\nX-Pstrykk-Event is the type. X-Pstrykk-Delivery equals body.id. X-Pstrykk-Timestamp is Unix time in seconds for that attempt. X-Pstrykk-Signature is \"sha256=\" followed by the lowercase hexadecimal HMAC-SHA256 of timestamp + \".\" + the exact raw UTF-8 request body, keyed by the saved webhook secret. Verify the signature with a timing-safe comparison against the raw body before parsing JSON; reserializing JSON may change the signed bytes. Check timestamp freshness (for example a five-minute tolerance), deduplicate durably by id, and check that the event/delivery headers match the body. The secret itself is not sent, and email/secret API credential headers are not sent. On retries, id, createdAt, and the JSON body stay the same; the timestamp and signature are generated again.\n\nAcknowledgement, retries, and ordering\nA completed HTTP 2xx response confirms delivery; HTTP 200 and 204 are both suitable. Respond promptly; an attempt has a 10-second deadline. Automatic attempts are dispatched by the server worker every five seconds in batches of up to 20. Non-2xx responses or connection failures are retried after configured delays of 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, and 24 hours, then the event is marked failed. These are per-attempt backoff delays, not a total delivery-time guarantee. Redirects are not followed and count as unconfirmed delivery. Pending events are stored in SQLite and can resume after a restart; server must be running to send them. The worker can send events concurrently, so arrival order is not guaranteed. Duplicate deliveries are possible: an acknowledgement may be lost or a worker may stop after the receiver processed the event. Do not interpret an older/out-of-order status as a guaranteed current payment snapshot. Disabling the webhook prevents new events; pending events encountered while disabled are marked failed. Finite retries do not guarantee eventual delivery.\n\nPanel test\nThe Test webhooka button sends POST /api/panel/webhook-test to the panel origin, not the /v1 API origin. Save the URL and secret first; unsaved input is not used. A valid panel session, active account, and X-CSRF-Token are required; API email/secret headers do not authorize this route. Tests are immediate and are not queued or retried automatically. The response displays ok, url, statusCode, durationMs, error, responseBody, and request. HTTP 200 from the panel endpoint only means the test was performed: inspect ok and the remote statusCode for the delivery result. The displayed response is limited to 4096 characters; it is not a guaranteed complete response body. A per-user, per-process five-second test throttle returns HTTP 429 for frequent requests.","x-documentation-language":"en"},"servers":[{"url":"/","description":"Same origin as the installed documentation. Use the actual deployment HTTPS origin; no public API hostname is asserted."}],"security":[{"MerchantEmail":[],"MerchantSecret":[]}],"tags":[{"name":"Health","description":"Authenticated liveness probe."},{"name":"Payments","description":"Create and inspect merchant-owned checkout links and explicitly synchronize status."},{"name":"Refunds","description":"Full or partial refund requests with duplicate-submission protection."},{"name":"Payment links","description":"Local deactivation of an unpaid pstrykk checkout link."},{"name":"Subscriptions","description":"Recurring card payments: a first checkout payment activates a fixed plan of recurring charges; list and cancel subscriptions."},{"name":"Balances","description":"Balances by currency and the first-payout eligibility gate."},{"name":"Payouts","description":"PLN payout requests; no idempotent replay mechanism."},{"name":"QR codes","description":"Payment-link QR and Polish domestic transfer QR in PNG or SVG."},{"name":"Documentation","description":"Public HTML documentation and the installed OpenAPI JSON."},{"name":"Webhooks","description":"Outgoing test, transaction, and refund notifications to a merchant-configured HTTPS receiver, plus the authenticated panel test."}],"paths":{"/v1/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Check authenticated API liveness","description":"Requires both authentication headers. Returns ok: true when this handler is reached. This is not a payment-service readiness test.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"}],"responses":{"200":{"description":"Authenticated liveness response.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"This route accepts GET only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-codeSamples":[{"lang":"Shell","label":"Health check","source":"curl --request GET \"${PSTRYKK_API_BASE_URL}/v1/health\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/payments":{"post":{"operationId":"createPayment","tags":["Payments"],"summary":"Create or recover a payment link","description":"Accepts creation of a checkout link with automatic capture and no card-tokenization option exposed to the caller. Requires a payment-enabled account. A new request atomically stores the local payment and a durable job, then returns HTTP 202 with id, paymentUrl, creationState pending, and linkActive false without waiting for the payment service. A background worker prepares the checkout. Read GET /v1/payments/{id} to check progress. Acceptance does not guarantee successful creation or payment. A replay of a tracked unfinished request returns HTTP 202 with the same ID; a ready replay returns HTTP 201 without repeating creation. Conflicting payment data or a rejected requestKey return HTTP 409. Preserve the exact requestKey on retries; do not generate a new key merely because a timeout occurred. Older reservations without a background job retain legacy recovery behavior and may return HTTP 409. creationState is separate from the financial status, which can initially be null.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"}],"responses":{"202":{"description":"Payment creation accepted for background processing. The local ID and paymentUrl are available, but the checkout is not ready yet. Read GET /v1/payments/{id} to check creationState. Acceptance does not guarantee successful creation or payment.","headers":{"Location":{"description":"Relative URL of the authenticated payment resource.","schema":{"type":"string"},"example":"/v1/payments/ABCDEFGHIJKLMNOP"},"Retry-After":{"description":"Suggested polling delay in seconds.","schema":{"type":"string"},"example":"1"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"example":{"id":"ABCDEFGHIJKLMNOP","creationState":"pending","creationError":null,"description":"Order 2026-1042","amountCents":1000,"currency":"EUR","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":false}}}},"201":{"description":"Payment created or an existing ready requestKey replay recovered. Both paths use HTTP 201. Null initial status is possible if the post-creation status refresh fails.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"example":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null}}}},"400":{"description":"Invalid creation field or request body. PLN is restricted to 500-600000 minor units. No top-level fields from other payment APIs are implicitly supported.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidKey":{"summary":"UUID v4 required","value":{"error":"requestKey must be a UUID v4."}},"plnBounds":{"summary":"PLN amount validation","value":{"error":"amountCents must be between 500 and 600000 for PLN."}},"language":{"summary":"Unsupported checkout language","value":{"error":"language must be one of: en, it, fr, de, es, pl, sk."}},"expiry":{"summary":"New reservation expiry outside the allowed period","value":{"error":"expiresAt must be between 1 second and 90 days from now."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Conflicting or rejected requestKey, account not ready, or an unresolved legacy creation without a background job. An id is included for key conflicts and unconfirmed reservations, but not universally. Tracked unfinished creation normally returns HTTP 202 instead.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"differentData":{"summary":"Existing key used with different payment data","value":{"error":"This requestKey belongs to different payment data.","id":"ABCDEFGHIJKLMNOP"}},"subscriptionKey":{"summary":"Key already used by POST /v1/subscriptions","value":{"error":"This requestKey belongs to a subscription."}},"rejectedKey":{"summary":"Only a deliberate new attempt can use a new key","value":{"error":"This payment request was rejected. Use a new requestKey for a new attempt.","id":"ABCDEFGHIJKLMNOP"}},"uncertain":{"summary":"Do not recreate the payment","value":{"error":"The result of creating payment ABCDEFGHIJKLMNOP could not be confirmed. Check GET /v1/payments/ABCDEFGHIJKLMNOP instead of creating a new payment.","id":"ABCDEFGHIJKLMNOP"}},"notReady":{"summary":"Stored reservation still has no checkout URL","value":{"error":"The payment URL is not available yet.","id":"ABCDEFGHIJKLMNOP"}},"recoveryFailed":{"summary":"Repeated requestKey still cannot be confirmed","value":{"error":"The result of creating payment ABCDEFGHIJKLMNOP could not be confirmed yet. Use POST /v1/payments/ABCDEFGHIJKLMNOP/sync.","id":"ABCDEFGHIJKLMNOP"}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"description":"No usable method, an explicitly unavailable method, or a payment-service business rejection. A rejected creation reservation cannot be replayed as a new attempt.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"none":{"summary":"At least one explicit method flag must be true","value":{"error":"Select at least one payment method."}},"unavailable":{"summary":"One explicit selection cannot be used","value":{"error":"A selected payment method is not available for this payment."}},"defaultsUnavailable":{"summary":"No default method remains usable","value":{"error":"No payment method is available for this payment. Check the enabled methods in your panel."}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/PaymentServiceError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"},"examples":{"minimalEnglish":{"summary":"PLN payment with an English checkout and account defaults","value":{"requestKey":"7d444840-9dc0-4b7a-a2c0-11e13f4c6b37","amountCents":12500,"description":"Order #2026-1042","language":"en"}},"selectedMethods":{"summary":"Explicit Visa, Mastercard, and BLIK selection","value":{"requestKey":"7d444840-9dc0-4b7a-a2c0-11e13f4c6b37","amountCents":12500,"description":"Order #2026-1042","language":"en","paymentMethods":{"VIS":true,"MSC":true,"BLI":true},"notificationEmail":"customer@example.com"}},"eurPayment":{"summary":"EUR payment without PLN-only BLIK","value":{"requestKey":"676f1c84-d2c7-45a8-a5b8-cde9b0113c03","amountCents":12500,"description":"Order #2026-1042","language":"en","currency":"EUR","paymentMethods":{"VIS":true,"MSC":true}}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Create an English-checkout payment","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/payments\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"requestKey\":\"7d444840-9dc0-4b7a-a2c0-11e13f4c6b37\",\"amountCents\":12500,\"description\":\"Order #2026-1042\",\"language\":\"en\"}'"}],"x-idempotency":{"field":"requestKey","scope":"merchant","replayStatus":[201,202],"replay":"Returns the existing stored payment, not the original response snapshot: HTTP 201 when ready, HTTP 202 for tracked unfinished creation; rejected keys return HTTP 409.","uncertainResult":"Use returned id to read/synchronize; never blindly change the key."}}},"/v1/payments/{id}":{"get":{"operationId":"getPayment","tags":["Payments"],"summary":"Read a payment with conditional refresh","description":"Returns a payment belonging to the authenticated merchant. For a payment tracked by the background creation queue whose creationState is not ready, returns the local state without waiting for a payment-service read, including pending, uncertain, and rejected states. Rejected creation details are returned in creationError. Ready payments use conditional payment-status refresh with stored-data fallback if refresh fails. Older unresolved reservations without a background job retain legacy recovery behavior and may return HTTP 409. No statusSyncedAt is exposed. This endpoint does not list payments.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Current local payment view; may be cached/stored rather than freshly synchronized. Examples deliberately do not claim a numeric statusId mapping or complete history; legacy/incomplete stored records can have null statusId.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"ready":{"summary":"Ready checkout; no current status or history yet","value":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null}},"settled":{"summary":"Settled payment; numeric status mapping intentionally not fabricated","value":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":"Settled","statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":"2030-01-15T10:05:00.000Z","refundedCents":0,"refundableCents":12500,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":false,"creationState":"ready","creationError":null}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"description":"This route accepts GET only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Legacy creation without a background job has not been confirmed and the attempted status recovery failed. Tracked pending, uncertain, and rejected creations are returned by GET with HTTP 200 and their local creationState instead.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unconfirmed":{"summary":"Keep the same payment ID","value":{"error":"The result of creating payment ABCDEFGHIJKLMNOP could not be confirmed yet. Try again shortly.","id":"ABCDEFGHIJKLMNOP"}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-codeSamples":[{"lang":"Shell","label":"Read a payment","source":"curl --request GET \"${PSTRYKK_API_BASE_URL}/v1/payments/ABCDEFGHIJKLMNOP\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/payments/{id}/sync":{"post":{"operationId":"synchronizePayment","tags":["Payments"],"summary":"Force payment status synchronization","description":"Attempts a current payment-service read, except while a tracked background creation is pending: then it returns the local payment view without contacting the payment service. Otherwise there is no stale-data success fallback. Successful synchronization does not guarantee checkout availability or linkActive true. Inspect tracked rejected creations through GET /v1/payments/{id}; this sync route returns 404 for rejected records. Empty body or any JSON object is accepted; arrays, null, primitives, invalid JSON, and oversized bodies are rejected.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Payment after a successful payment-service status read and local update. Examples deliberately do not claim a numeric statusId mapping or complete history; legacy/incomplete stored records can have null statusId.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"example":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":"Settled","statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":"2030-01-15T10:05:00.000Z","refundedCents":0,"refundableCents":12500,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":false,"creationState":"ready","creationError":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"The payment-service reference disagrees with the stored payment identity.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identifierMismatch":{"summary":"Manual reconciliation required","value":{"error":"Payment identifier mismatch."}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Payment-service network/authentication error or incomplete/unverifiable payment data. There is no success fallback to the stored payment.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"incomplete":{"summary":"Missing required transaction/status data","value":{"error":"Incomplete payment status received."}},"amount":{"summary":"Amount verification failed","value":{"error":"Could not confirm the payment amount."}},"currency":{"summary":"Currency verification failed","value":{"error":"Could not confirm the payment currency."}}}}}},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":false,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRequest"},"examples":{"empty":{"summary":"No options are required","value":{}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Force a current status read","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/payments/ABCDEFGHIJKLMNOP/sync\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{}'"}]}},"/v1/payments/{id}/refund":{"post":{"operationId":"refundPayment","tags":["Refunds"],"summary":"Request a full or partial refund","description":"Requires creation to be ready and normalized status Settled, or Partially refunded with accepted local refunds that make the remaining amount verifiable. Full refund means explicitly requesting the remaining amount. Pending/unconfirmed earlier actions block new ones; externally initiated partial refunds require support. Duplicate refund requestKey detection returns 409 with refundId when reached; it does not replay the original success, and earlier validation/synchronization may fail first. If the outcome cannot be confirmed, keep refundId, do not retry with a new key, and contact support.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Refund request accepted. The payment view reflects locally accepted refund totals; its status/history may still be the pre-refund state. Acceptance is not final settlement. Examples deliberately do not claim a numeric statusId mapping or complete history; legacy/incomplete stored records can have null statusId.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"},"example":{"refund":{"id":"284b4b65-6ca6-44bf-824c-24d403ae9c6d","amountCents":2500,"currency":"PLN","state":"accepted","createdAt":"2030-01-15T11:00:00.000Z","message":"OK"},"payment":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":"Settled","statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":"2030-01-15T10:05:00.000Z","refundedCents":2500,"refundableCents":10000,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":false,"creationState":"ready","creationError":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Duplicate, nonrefundable state, unverifiable previous partial refunds, or an unresolved financial result. Do not change the key to bypass an uncertain refund.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"duplicate":{"summary":"Duplicate suppression, not response replay","value":{"error":"This operation has already been submitted. Do not submit it again.","refundId":"284b4b65-6ca6-44bf-824c-24d403ae9c6d"}},"unconfirmed":{"summary":"Contact support; do not resubmit","value":{"error":"The result of the refund could not be confirmed. Do not retry; contact support.","refundId":"284b4b65-6ca6-44bf-824c-24d403ae9c6d"}},"blocked":{"summary":"A previous action is unresolved","value":{"error":"A previous operation on this payment is awaiting confirmation. Contact support."}},"externalPartial":{"summary":"Earlier partial refunds cannot be reconciled locally","value":{"error":"Earlier refunds of this payment cannot be verified. Contact support."}},"state":{"summary":"Current payment is not refundable","value":{"error":"This payment cannot be refunded in its current state."}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"description":"Amount exceeds remaining refundable capacity, or the refund/status service returned a definite rejection. refundId may be included, but is not guaranteed.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"overCapacity":{"summary":"Do not exceed refundableCents","value":{"error":"amountCents exceeds the refundable amount (10000)."}},"rejected":{"summary":"Definite rejection","value":{"error":"Refund rejected.","refundId":"284b4b65-6ca6-44bf-824c-24d403ae9c6d"}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/PaymentServiceError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"},"examples":{"partial":{"summary":"Refund 25.00 in the original payment currency","value":{"requestKey":"474f6a45-7a56-4e48-8d2a-75e38447e31a","amountCents":2500}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Request a partial refund","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/payments/ABCDEFGHIJKLMNOP/refund\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"requestKey\":\"474f6a45-7a56-4e48-8d2a-75e38447e31a\",\"amountCents\":2500}'"}],"x-idempotency":{"field":"requestKey","scope":"merchant-wide refund actions","replayStatus":409,"replay":"Duplicate suppression only; the original successful response is not replayed.","uncertainResult":"Do not retry; preserve refundId and contact support."}}},"/v1/payments/{id}/link":{"delete":{"operationId":"deactivatePaymentLink","tags":["Payment links"],"summary":"Deactivate an unpaid checkout link locally","description":"Allowed only for Created, Initialized, or Opened after normalization, with no pending/unconfirmed action and no previous local deactivation. An empty/unknown status is not sufficient. Does not require the link to be unexpired and does not issue a cancellation to the payment service. It records a local deactivation so linkActive becomes false; paymentUrl and the financial status/history remain present. It cannot undo a settled payment or guarantee cancellation of an already-started remote checkout. A repeat returns 409 rather than returning the original response.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Locally deactivated payment; linkActive is false.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"example":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":"Initialized","statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":false,"creationState":"ready","creationError":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"description":"This route accepts DELETE only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"DELETE"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Previously deactivated link, unresolved operation, or a status that is no longer eligible for local deactivation.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"already":{"summary":"Not replay-idempotent","value":{"error":"The payment link is already deactivated."}},"state":{"summary":"Status no longer permits local link deactivation","value":{"error":"The link of this payment can no longer be deactivated."}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-codeSamples":[{"lang":"Shell","label":"Deactivate a link","source":"curl --request DELETE \"${PSTRYKK_API_BASE_URL}/v1/payments/ABCDEFGHIJKLMNOP/link\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/subscriptions":{"post":{"operationId":"createSubscription","tags":["Subscriptions"],"summary":"Create or recover a subscription","description":"Starts a recurring card-payment plan. Requires a payment-enabled account. The subscription begins with a first payment of amountCents paid through a regular checkout link (transactionId, paymentUrl). Only card methods enabled for the account are offered (Visa, Mastercard, American Express, JCB, Diners Club, Discover, UnionPay), because the card is stored for later charges; BLIK, bank transfer, Klarna, Google Pay, and Apple Pay are never offered, and paymentMethods is not supported. After the first payment is paid, the payment service automatically activates the plan: recurringAmountCents every monthsFrequency months, starting on startingDate, totalPayments times, without further payer interaction. A new request atomically reserves the first payment, the subscription record, and a durable background job, then returns HTTP 202 with id, transactionId, paymentUrl, and creationState creating without waiting for the payment service. Poll GET /v1/subscriptions or GET /v1/payments/{transactionId}; the Location path supports DELETE only. Acceptance does not guarantee successful creation or payment. If background creation is rejected (for example, no card method is enabled), the subscription is hidden from GET /v1/subscriptions, DELETE returns 404, GET /v1/payments/{transactionId} shows creationState rejected with creationError, and the requestKey cannot be reused. requestKey shares one namespace with POST /v1/payments: a key used for a regular payment is rejected here, and vice versa. A replay with the same requestKey and identical data returns the stored subscription without creating another: HTTP 201 when creationState is ready, otherwise HTTP 202. All fields are validated again on replay, so a replay after startingDate has passed returns 400. Omitting expiresAt, redirectWebsite, or redirectTime on a replay reuses the stored values. Keep the exact requestKey on retries; do not generate a new key merely because a timeout occurred. status stays null until the first payment is paid and the plan is linked.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"}],"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields, including paymentMethods, are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"},"examples":{"monthly":{"summary":"Monthly PLN plan, Polish checkout, 12 renewals","value":{"requestKey":"b3d4f6a8-1c2e-4f5a-9b7c-2d3e4f5a6b7c","notificationEmail":"customer@example.com","subscriberName":"Jan Kowalski","description":"Premium plan","amountCents":4900,"recurringAmountCents":4900,"monthsFrequency":1,"totalPayments":12,"startingDate":"15-02-2030"}},"quarterlyEur":{"summary":"Quarterly EUR plan with a lower first payment, English checkout, explicit link expiry and return website","value":{"requestKey":"c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d","notificationEmail":"customer@example.com","subscriberName":"Anna Nowak","description":"Quarterly box","amountCents":1500,"recurringAmountCents":3900,"currency":"EUR","language":"en","monthsFrequency":3,"totalPayments":4,"startingDate":"01-04-2030","expiresAt":"2030-01-22T12:00:00Z","redirectWebsite":"https://www.test.pl/powrot","redirectTime":5}}}}}},"responses":{"202":{"description":"Subscription creation accepted for background processing, or a replay of a request that is not ready yet. id, transactionId, and paymentUrl are available, but the checkout may not be ready. Acceptance does not guarantee successful creation or payment.","headers":{"Location":{"description":"Relative URL of the subscription resource. This path supports DELETE (cancellation) only; GET returns 405. Read progress with GET /v1/subscriptions or GET /v1/payments/{transactionId}.","schema":{"type":"string"},"example":"/v1/subscriptions/QRSTUVWXYZABCDEF"},"Retry-After":{"description":"Suggested polling delay in seconds. Sent only when creationState is not ready.","schema":{"type":"string"},"example":"1"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"},"example":{"id":"QRSTUVWXYZABCDEF","transactionId":"ABCDEFGHIJKLMNOP","storeId":"3f0c2a52-8a51-4c43-9d0e-6a8f2b1c7e45","subscriberName":"Jan Kowalski","description":"Premium plan","notificationEmail":"customer@example.com","amountCents":4900,"recurringAmountCents":4900,"currency":"PLN","language":"pl","monthsFrequency":1,"startingDate":"15-02-2030","totalPayments":12,"creationState":"creating","status":null,"statusId":null,"paymentsMade":null,"lastChargeDate":null,"nextChargeDate":null,"cancelledAt":null,"createdAt":"2030-01-15T10:00:00.000Z","paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP"}}}},"201":{"description":"Replay of a subscription whose first-payment checkout is ready. creationState ready does not mean the first payment was paid; status remains null until the plan is linked after payment.","headers":{"Location":{"description":"Relative URL of the subscription resource. This path supports DELETE (cancellation) only; GET returns 405. Read progress with GET /v1/subscriptions or GET /v1/payments/{transactionId}.","schema":{"type":"string"},"example":"/v1/subscriptions/QRSTUVWXYZABCDEF"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"},"example":{"id":"QRSTUVWXYZABCDEF","transactionId":"ABCDEFGHIJKLMNOP","storeId":"3f0c2a52-8a51-4c43-9d0e-6a8f2b1c7e45","subscriberName":"Jan Kowalski","description":"Premium plan","notificationEmail":"customer@example.com","amountCents":4900,"recurringAmountCents":4900,"currency":"PLN","language":"pl","monthsFrequency":1,"startingDate":"15-02-2030","totalPayments":12,"creationState":"ready","status":null,"statusId":null,"paymentsMade":null,"lastChargeDate":null,"nextChargeDate":null,"cancelledAt":null,"createdAt":"2030-01-15T10:00:00.000Z","paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP"}}}},"400":{"description":"Invalid request body or field. Validation also applies to replays.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidKey":{"summary":"UUID v4 required","value":{"error":"requestKey must be a UUID v4."}},"emailRequired":{"summary":"notificationEmail missing or not a string","value":{"error":"notificationEmail is required for subscriptions."}},"emailInvalid":{"summary":"notificationEmail validation","value":{"error":"notificationEmail must contain one valid email address."}},"subscriberName":{"summary":"subscriberName validation","value":{"error":"subscriberName must be a string of 1 to 200 characters."}},"description":{"summary":"description validation","value":{"error":"description must be a string of 1 to 450 characters."}},"recurringBounds":{"summary":"Recurring amount outside 50-250000","value":{"error":"recurringAmountCents must be between 50 and 250000."}},"plnBounds":{"summary":"PLN first-payment bounds","value":{"error":"amountCents must be between 500 and 600000 for PLN."}},"frequency":{"summary":"monthsFrequency outside 1-36","value":{"error":"monthsFrequency must be an integer between 1 and 36."}},"totalPayments":{"summary":"totalPayments outside 1-999999","value":{"error":"totalPayments must be an integer between 1 and 999999."}},"dateFormat":{"summary":"startingDate is not dd-mm-yyyy","value":{"error":"startingDate must use the dd-mm-yyyy format."}},"datePast":{"summary":"startingDate is not a real calendar date or is not in the future","value":{"error":"startingDate must be a valid future date."}},"expiry":{"summary":"First-payment link expiry outside the allowed period","value":{"error":"expiresAt must be between 1 second and 90 days from now."}},"redirectTime":{"summary":"Invalid automatic-return delay","value":{"error":"redirectTime must be an integer from 1 to 60 seconds."}}}}}},"401":{"description":"Missing, invalid, oversized, or repeated email/secret credentials, or the store bound to the credentials is no longer active.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"credentials":{"summary":"Invalid credentials","value":{"error":"Invalid email or secret."}},"inactiveStore":{"summary":"Store deleted","value":{"error":"The store is no longer active."}}}}}},"409":{"description":"requestKey conflict, rejected or unconfirmed creation, or account not ready. Do not create a new subscription with a new key while an id is reported as unconfirmed.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"differentData":{"summary":"Existing key used with different subscription data","value":{"error":"This requestKey belongs to different subscription data.","id":"ABCDEFGHIJKLMNOP"}},"regularPayment":{"summary":"Key already used by POST /v1/payments","value":{"error":"This requestKey belongs to a regular payment.","id":"ABCDEFGHIJKLMNOP"}},"otherStore":{"summary":"Key used by another store of the same account","value":{"error":"This requestKey belongs to another store. Use a new requestKey."}},"rejectedKey":{"summary":"Background creation was rejected; only a deliberate new attempt can use a new key","value":{"error":"This subscription request was rejected. Use a new requestKey for a new attempt.","id":"ABCDEFGHIJKLMNOP"}},"notConfirmed":{"summary":"Reservation without a background job is still unresolved","value":{"error":"The subscription has not been confirmed yet. Try again shortly.","id":"ABCDEFGHIJKLMNOP"}},"accountSetup":{"summary":"Account not ready","value":{"error":"The account is not set up for payments yet."}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"Shell","label":"Create a monthly subscription","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/subscriptions\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"requestKey\":\"b3d4f6a8-1c2e-4f5a-9b7c-2d3e4f5a6b7c\",\"notificationEmail\":\"customer@example.com\",\"subscriberName\":\"Jan Kowalski\",\"description\":\"Premium plan\",\"amountCents\":4900,\"recurringAmountCents\":4900,\"monthsFrequency\":1,\"totalPayments\":12,\"startingDate\":\"15-02-2030\"}'"}]},"get":{"operationId":"listSubscriptions","tags":["Subscriptions"],"summary":"List subscriptions","description":"Returns subscriptions of the store bound to the credentials, newest first (createdAt descending, then id descending). Creation-rejected subscriptions are excluded. The response contains locally stored data and does not query the payment service; status, statusId, paymentsMade, lastChargeDate, nextChargeDate, and cancelledAt are refreshed by background synchronization, so they can lag behind the payment service. There is no single-subscription GET route; find a subscription by id in this list. In list items, language is currently always pl; read GET /v1/payments/{transactionId} for the actual checkout language and the first-payment status. A page beyond pages returns an empty items array.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/SubscriptionPage"},{"$ref":"#/components/parameters/SubscriptionPageSize"}],"responses":{"200":{"description":"One page of subscriptions.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionList"},"example":{"items":[{"id":"QRSTUVWXYZABCDEF","transactionId":"ABCDEFGHIJKLMNOP","storeId":"3f0c2a52-8a51-4c43-9d0e-6a8f2b1c7e45","subscriberName":"Jan Kowalski","description":"Premium plan","notificationEmail":"customer@example.com","amountCents":4900,"recurringAmountCents":4900,"currency":"PLN","language":"pl","monthsFrequency":1,"startingDate":"15-02-2030","totalPayments":12,"creationState":"ready","status":"Active","statusId":1,"paymentsMade":0,"lastChargeDate":null,"nextChargeDate":"2030-02-15T00:00:00.000Z","cancelledAt":null,"createdAt":"2030-01-15T10:00:00.000Z","paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP"},{"id":"RSTUVWXYZABCDEFG","transactionId":"BCDEFGHIJKLMNOPQ","storeId":"3f0c2a52-8a51-4c43-9d0e-6a8f2b1c7e45","subscriberName":"Anna Nowak","description":"Premium plan","notificationEmail":"customer@example.com","amountCents":4900,"recurringAmountCents":4900,"currency":"PLN","language":"pl","monthsFrequency":1,"startingDate":"15-02-2030","totalPayments":12,"creationState":"ready","status":null,"statusId":null,"paymentsMade":null,"lastChargeDate":null,"nextChargeDate":null,"cancelledAt":null,"createdAt":"2030-01-14T08:00:00.000Z","paymentUrl":"https://pay.pstrykk.pl/BCDEFGHIJKLMNOPQ"}],"total":2,"page":1,"pageSize":25,"pages":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"Methods other than GET and POST. The Allow header currently lists only GET, although POST is also supported on this path.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"Currently GET only; POST is also supported.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"Shell","label":"List subscriptions","source":"curl --request GET \"${PSTRYKK_API_BASE_URL}/v1/subscriptions?page=1&pageSize=25\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/subscriptions/{id}":{"delete":{"operationId":"cancelSubscription","tags":["Subscriptions"],"summary":"Cancel a subscription","description":"Asks the payment service to set the recurring plan to Cancelled, which stops future recurring charges. Possible only after the first payment has been paid and the plan has been linked locally (status is non-null); before that the request returns 409. To stop an unpaid first payment, use DELETE /v1/payments/{transactionId}/link. On success, status becomes Cancelled, cancelledAt is set, and the response includes cancelled true. Cancellation does not refund the first payment or earlier recurring charges; refund the first payment with POST /v1/payments/{transactionId}/refund. The operation is not blocked locally after a cancellation: repeating it sends the same Cancelled status again and returns 200 when confirmed, so retrying after a 502 is safe. If a later background synchronization reports a different status from the payment service, status is overwritten and cancelledAt becomes null. Subscriptions of another store or account, and creation-rejected subscriptions, return 404.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/SubscriptionId"}],"responses":{"200":{"description":"Cancellation confirmed by the payment service.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelledSubscription"},"example":{"id":"QRSTUVWXYZABCDEF","transactionId":"ABCDEFGHIJKLMNOP","storeId":"3f0c2a52-8a51-4c43-9d0e-6a8f2b1c7e45","subscriberName":"Jan Kowalski","description":"Premium plan","notificationEmail":"customer@example.com","amountCents":4900,"recurringAmountCents":4900,"currency":"PLN","language":"pl","monthsFrequency":1,"startingDate":"15-02-2030","totalPayments":12,"creationState":"ready","status":"Cancelled","statusId":4,"paymentsMade":0,"lastChargeDate":null,"nextChargeDate":"2030-02-15T00:00:00.000Z","cancelledAt":"2030-01-20T09:30:00.000Z","createdAt":"2030-01-15T10:00:00.000Z","paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","cancelled":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Invalid, unknown, foreign-owned, other-store, or creation-rejected subscription identifier.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Subscription not found."}}}},"405":{"description":"This route accepts DELETE only; there is no single-subscription GET.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"DELETE"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"The plan is not linked yet (the first payment is unpaid or not yet synchronized), or the subscription has incomplete account data. Nothing was cancelled.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notLinked":{"summary":"First payment not paid or plan not linked yet; message is in Polish","value":{"error":"Brak UUID operatora. Anulowanie nie zostało wykonane; pierwsza płatność może nadal być aktywna."}},"missingCompany":{"summary":"Incomplete account data","value":{"error":"Missing subscription company."}}}}}},"422":{"description":"The payment service rejected the cancellation.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Request failed (HTTP 422)."}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"The payment service is unavailable, returned invalid data, or did not confirm the cancellation. The outcome may be unconfirmed: check GET /v1/subscriptions and repeat DELETE.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notConfirmed":{"summary":"Cancellation not confirmed; message is in Polish","value":{"error":"Operator nie potwierdził anulowania. Ponów sprawdzenie."}},"statuses":{"summary":"Invalid status list from the payment service","value":{"error":"Invalid subscription statuses."}},"noCancelled":{"summary":"Cancelled status unavailable","value":{"error":"Missing Cancelled status."}},"unavailable":{"summary":"Network failure or timeout","value":{"error":"Payment service is unavailable."}}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Cancel a subscription","source":"curl --request DELETE \"${PSTRYKK_API_BASE_URL}/v1/subscriptions/QRSTUVWXYZABCDEF\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/balance":{"get":{"operationId":"getBalance","tags":["Balances"],"summary":"Read balances and first-payout eligibility","description":"Fetches account balances by currency and reports available/pending processing funds separately from held risk reserve and security deposit. A supplied but unreported valid currency yields one zero-filled balance row. Without a filter the balances array can be empty. payoutGate is present only without a filter or for PLN. Passing the gate is independent of having enough available funds. The API does not perform currency conversion for this gate.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/BalanceCurrency"}],"responses":{"200":{"description":"Balances, plus payoutGate only for an unfiltered or PLN request.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"},"examples":{"plnBeforeThreshold":{"summary":"PLN funds with first-payout gate still locked","value":{"balances":[{"currency":"PLN","availableCents":70000,"pendingCents":5000,"rollingReserveCents":0,"securityDepositCents":0}],"payoutGate":{"allowed":false,"reason":"turnover","minPayoutCents":100000,"turnoverCents":75000,"unlocksAt":null}}},"otherCurrency":{"summary":"No payoutGate for an explicit EUR filter","value":{"balances":[{"currency":"EUR","availableCents":0,"pendingCents":0,"rollingReserveCents":0,"securityDepositCents":0}]}},"gatePassed":{"summary":"PLN gate passed; turnover is no longer recalculated","value":{"balances":[{"currency":"PLN","availableCents":125000,"pendingCents":0,"rollingReserveCents":0,"securityDepositCents":0}],"payoutGate":{"allowed":true,"reason":null,"minPayoutCents":100000,"turnoverCents":null,"unlocksAt":"2030-01-08T10:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"This route accepts GET only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Account is not payment-enabled.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"setup":{"summary":"Payment setup incomplete","value":{"error":"The account is not set up for payments yet."}}}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/PaymentServiceError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-codeSamples":[{"lang":"Shell","label":"Read PLN balance and gate","source":"curl --request GET \"${PSTRYKK_API_BASE_URL}/v1/balance?currency=PLN\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""},{"lang":"Shell","label":"Read EUR balance without payout gate","source":"curl --request GET \"${PSTRYKK_API_BASE_URL}/v1/balance?currency=EUR\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\""}]}},"/v1/balance/payout":{"post":{"operationId":"requestPayout","tags":["Payouts"],"summary":"Request a PLN payout","description":"Uses the account-configured payout destination. Requires a positive integer amount in grosze, sufficient available PLN balance, and a passed first-payout gate: qualifying gross PLN turnover must first be recorded as strictly greater than the configured threshold, then seven full days must pass. No requestKey, idempotency header, destination selection, fee estimate, execution-date guarantee, or payout-status lookup is implemented. Sending such fields does not add those capabilities. Do not automatically retry after a timeout, disconnect, or an unconfirmed 502: check balance/account records and reconcile first. A success response means the request was accepted, not that the beneficiary bank has received the funds.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"}],"responses":{"200":{"description":"Payout request accepted; additional details are optional and have no stable schema.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutResponse"},"example":{"success":true,"amountCents":50000,"currency":"PLN","message":"Payout request accepted."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"First-payout gate is not yet passed, or the account/threshold configuration is invalid. Gate rejection includes payoutGate and availableCents.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"firstPayout":{"summary":"Turnover or waiting period blocks payout","value":{"error":"The first payout is not available yet.","payoutGate":{"allowed":false,"reason":"turnover","minPayoutCents":100000,"turnoverCents":75000,"unlocksAt":null},"availableCents":70000}},"threshold":{"summary":"Invalid gate configuration","value":{"error":"Invalid payout threshold configuration."}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"description":"Amount exceeds available PLN funds or a definite payout/payment-service business rejection occurred.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient":{"summary":"Amount exceeds available balance","value":{"error":"amountCents exceeds the available balance.","availableCents":40000}},"rejected":{"summary":"Payment-service rejection","value":{"error":"Payout rejected."}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Service failure or unconfirmed payout result. A payout may have been accepted even though this response is an error; do not blindly retry.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unconfirmed":{"summary":"Reconcile before any further submission","value":{"error":"The result of the payout could not be confirmed. Check your balance before retrying."}},"balanceRead":{"summary":"Could not read prerequisites","value":{"error":"Could not fetch the balance. Payment service is unavailable."}}}}}},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutRequest"},"examples":{"pln":{"summary":"Request 500.00 PLN","value":{"amountCents":50000,"currency":"PLN"}}}}}},"x-idempotency":{"supported":false,"ignoredFields":["requestKey"],"uncertainResult":"Check the balance and reconcile; do not automatically retry."},"x-codeSamples":[{"lang":"Shell","label":"Request a payout only after reconciling prior attempts","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/balance/payout\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"amountCents\":50000,\"currency\":\"PLN\"}'"}]}},"/v1/payments/{id}/qr":{"post":{"operationId":"createPaymentQr","tags":["QR codes"],"summary":"Generate a payment-link QR image","description":"Therefore a valid, ready, active payment reaches HTTP 500 instead of the intended image response. The intended operation encodes the public paymentUrl and returns a branded PNG or SVG with payment metadata and an inline filename. Requires ready creation, a stored checkout URL, and linkActive true. Does not return JSON or a QR URL and does not create a payment. Metadata text is Polish regardless of this English documentation.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"},{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Raw image bytes, not JSON or base64. The request format selects PNG or SVG; Accept is not used for negotiation. SVG carries a restrictive Content-Security-Policy. Intended success contract.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Content-Length":{"$ref":"#/components/headers/ContentLength"},"Content-Security-Policy":{"$ref":"#/components/headers/ContentSecurityPolicy"},"Content-Disposition":{"$ref":"#/components/headers/QrDisposition"}},"content":{"image/png":{"schema":{"type":"string","format":"binary","description":"PNG file bytes; square size from the request."}},"image/svg+xml":{"schema":{"type":"string","format":"binary","description":"UTF-8 SVG image; square size from the request."}}}},"400":{"description":"Invalid request JSON/object body, missing/invalid size or format, or QR capacity/rendering failure.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidSize":{"summary":"Image size is mandatory","value":{"error":"size must be an integer between 64 and 1024 (pixels)."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"409":{"description":"Payment creation is not ready, no checkout URL is stored, or the local link is inactive.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notReady":{"summary":"Synchronize the payment before requesting a QR image","value":{"error":"The payment is not ready yet."}},"inactive":{"summary":"Expired, deactivated, or noninitial payment","value":{"error":"The payment link is not active."}}}}}},"413":{"$ref":"#/components/responses/TooLarge"},"500":{"description":"Other unexpected errors use the same envelope.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrOptions"},"examples":{"png":{"summary":"512-pixel PNG","value":{"size":512,"format":"png"}},"svg":{"summary":"512-pixel SVG","value":{"size":512,"format":"svg"}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Save payment PNG after repairing the metadata function","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/payments/ABCDEFGHIJKLMNOP/qr\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"size\":512,\"format\":\"png\"}' \\\n  --output payment-qr.png"}]}},"/v1/micro":{"post":{"operationId":"createTransferQr","tags":["QR codes"],"summary":"Generate a Polish bank-transfer QR image","description":"Generates a ZBP Standard 2D Polish domestic PLN transfer code. Validates the Polish NRB bank-account checksum and, when supplied, the Polish NIP checksum. Recipient and title are trimmed, limited to 20 and 32 Unicode code points, and cannot contain vertical bars or ASCII control characters. The amount is 1-999999 grosze. Final payload length cannot exceed 160 JavaScript string code units. A currency field is ignored; this route always encodes PLN. Returns PNG/SVG bytes selected by format and does not add payment metadata or a Content-Disposition filename. It does not initiate a transfer, verify bank-account ownership, check the recipient against a registry, create a checkout link, or store a payment.","parameters":[{"$ref":"#/components/parameters/EmailHeader"},{"$ref":"#/components/parameters/SecretHeader"}],"responses":{"200":{"description":"Raw image bytes, not JSON or base64. The request format selects PNG or SVG; Accept is not used for negotiation. SVG carries a restrictive Content-Security-Policy. No payment record is created and no bank transfer is executed.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Content-Length":{"$ref":"#/components/headers/ContentLength"},"Content-Security-Policy":{"$ref":"#/components/headers/ContentSecurityPolicy"}},"content":{"image/png":{"schema":{"type":"string","format":"binary","description":"PNG file bytes; square size from the request."}},"image/svg+xml":{"schema":{"type":"string","format":"binary","description":"UTF-8 SVG image; square size from the request."}}}},"400":{"description":"Malformed JSON/object body, invalid QR options, invalid account/NIP checksum, invalid transfer text, or amount outside the fixed PLN limits.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"size":{"summary":"No implicit image size","value":{"error":"size must be an integer between 64 and 1024 (pixels)."}},"format":{"summary":"No implicit output format","value":{"error":"format must be 'png' or 'svg'."}},"account":{"summary":"Valid NRB checksum required","value":{"error":"account must be a valid 26-digit Polish bank account number (NRB), optionally prefixed with PL."}},"amount":{"summary":"Transfer-specific amount range","value":{"error":"amountCents must be an integer between 1 and 999999 (0.01 to 9999.99 PLN)."}},"nip":{"summary":"NIP checksum failure","value":{"error":"nip must be a valid 10-digit Polish tax identification number."}},"tooSmall":{"summary":"Increase size even though it was within the nominal range","value":{"error":"The requested size is too small for the amount of data. Increase size."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"This route accepts POST only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"413":{"$ref":"#/components/responses/TooLarge"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQrRequest"},"examples":{"transferPng":{"summary":"Domestic PLN transfer code","value":{"account":"PL61109010140000071219812874","recipient":"Example Store","title":"Order 2026-1042","amountCents":12500,"size":512,"format":"png"}},"transferSvg":{"summary":"Domestic PLN transfer code as SVG","value":{"account":"PL61109010140000071219812874","recipient":"Example Store","title":"Order 2026-1042","amountCents":12500,"size":512,"format":"svg"}}}}}},"x-codeSamples":[{"lang":"Shell","label":"Save a transfer PNG","source":"curl --request POST \"${PSTRYKK_API_BASE_URL}/v1/micro\" \\\n  --header \"email: ${PSTRYKK_EMAIL}\" \\\n  --header \"secret: ${PSTRYKK_SECRET}\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-raw '{\"account\":\"PL61109010140000071219812874\",\"recipient\":\"Example Store\",\"title\":\"Order 2026-1042\",\"amountCents\":12500,\"size\":512,\"format\":\"png\"}' \\\n  --output transfer-qr.png"}]}},"/v1/docs":{"get":{"operationId":"getDocumentation","tags":["Documentation"],"summary":"Open the public HTML documentation","description":"Public: no email or secret required. This built-in page is a read-only reference, not Swagger UI. The documentation is only as current as the installed file. Missing, unreadable, or invalid JSON returns 503.","responses":{"200":{"description":"English HTML documentation rendered directly from the installed OpenAPI JSON. The lightweight renderer displays descriptions as plain text; no interactive API console or scripts are included.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Content-Length":{"$ref":"#/components/headers/ContentLength"},"Content-Security-Policy":{"$ref":"#/components/headers/ContentSecurityPolicy"},"Referrer-Policy":{"$ref":"#/components/headers/ReferrerPolicy"}},"content":{"text/html":{"schema":{"type":"string","description":"UTF-8 HTML document."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"405":{"description":"This public route accepts GET only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The installed documentation file is missing, unreadable, invalid JSON, or not a JSON object.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"documentationUnavailable":{"value":{"error":"The documentation is temporarily unavailable."}}}}}}},"security":[]}},"/v1/openapi":{"get":{"operationId":"getOpenApiDocument","tags":["Documentation"],"summary":"Download the installed OpenAPI JSON","description":"Public: no email or secret required. Returns the installed JSON file verbatim as application/json; charset=utf-8. No CORS headers are added, so importing this URL directly into an external browser-hosted documentation tool can be blocked by that browser; download/import the file instead, serve the tool from the same origin, or configure CORS at the reverse proxy. Missing, unreadable, or invalid JSON returns 503.","responses":{"200":{"description":"The original installed OpenAPI document bytes.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Content-Length":{"$ref":"#/components/headers/ContentLength"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"405":{"description":"This public route accepts GET only.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Allow":{"description":"The single supported HTTP method for this route.","schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed."}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The installed documentation file is missing, unreadable, invalid JSON, or not a JSON object.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"documentationUnavailable":{"value":{"error":"The documentation is temporarily unavailable."}}}}}}},"security":[]}},"/api/panel/webhook-test":{"post":{"operationId":"testMerchantWebhookFromPanel","tags":["Webhooks"],"summary":"Send a test webhook from the authenticated panel","description":"Panel-only endpoint on the panel origin; not a /v1 API endpoint. Requires the existing authenticated panel session cookie (cookie name is deployment-defined by SESSION_COOKIE), onboarded=1, and a valid X-CSRF-Token from the panel. API email/secret headers do not authorize this request. security=[] here removes the inherited /v1 merchant-header requirement; it DOES NOT mean anonymous access is permitted. The session requirement is recorded in x-panel-session-required because the supplied files do not specify the actual cookie name. Uses saved webhook_url/webhook_secret, not unsaved form fields. Sends a single test event and returns the receiver result. HTTP 200 can contain ok=false; inspect the response body. Per-user, per-process five-second throttle. The frontend displays the response as text.","servers":[{"url":"https://{panelHost}","description":"Panel origin only; replace panelHost for your deployment. The original server default is pstrykk.pl.","variables":{"panelHost":{"default":"pstrykk.pl","description":"Host serving the merchant panel, not the /v1 API host."}}}],"security":[],"x-panel-session-required":true,"parameters":[{"name":"X-CSRF-Token","in":"header","required":true,"description":"CSRF token of the authenticated panel session, read from panel-csrf in the panel HTML.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"description":"The panel sends {}. The endpoint uses stored configuration and does not read override fields from the request body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}},"responses":{"200":{"description":"The test attempt finished. Check ok/statusCode to determine acknowledgement; remote failures also use this HTTP 200 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResponse"},"example":{"ok":true,"url":"https://merchant.example/webhook","statusCode":200,"durationMs":125,"error":null,"responseBody":"{\"received\":true}","request":{"id":"evt_test_0123456789abcdef01234567","type":"test","createdAt":"2030-09-15T12:00:00.000Z","data":{"message":"Testowy webhook pstrykk."}}}}}},"401":{"description":"Missing/expired panel session or missing user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account inactive or invalid/missing panel CSRF token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Only POST is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Allow":{"schema":{"type":"string","const":"POST"}}}},"422":{"description":"Save both a receiver URL and a webhook secret before testing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Another test was requested less than five seconds ago for this user in this server process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"MerchantEmail":{"type":"apiKey","in":"header","name":"email","description":"Merchant email header. Must be used together with MerchantSecret, not as an alternative."},"MerchantSecret":{"type":"apiKey","in":"header","name":"secret","description":"Original opaque merchant API secret header. Must be used together with MerchantEmail. No Bearer prefix."},"WebhookSignature":{"type":"apiKey","in":"header","name":"X-Pstrykk-Signature","description":"Computed HMAC-SHA256 signature, NOT a static API key: sha256=hex(HMAC_SHA256(webhook_secret, X-Pstrykk-Timestamp + \".\" + raw UTF-8 body)). Require the signed timestamp and verify the exact raw body. The webhook secret is configured in the merchant panel and is not transmitted."}},"parameters":{"EmailHeader":{"name":"email","in":"header","required":true,"description":"Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased.","schema":{"type":"string","minLength":1,"maxLength":254},"example":"merchant@example.com"},"SecretHeader":{"name":"secret","in":"header","required":true,"description":"Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side.","schema":{"type":"string","minLength":1,"maxLength":1024,"format":"password","writeOnly":true}},"SubscriptionId":{"name":"id","in":"path","required":true,"description":"Identifier of a subscription belonging to the authenticated merchant and the store bound to the credentials. This is the subscription id, not transactionId. Invalid, unknown, foreign-owned, other-store, or creation-rejected identifiers return 404.","schema":{"$ref":"#/components/schemas/SubscriptionId"}},"SubscriptionPage":{"name":"page","in":"query","required":false,"description":"1-based page number. Missing, zero, negative, or non-numeric values mean 1. Send a positive integer; fractional values are not supported.","schema":{"type":"integer","minimum":1,"default":1},"example":1},"SubscriptionPageSize":{"name":"pageSize","in":"query","required":false,"description":"Items per page. Missing, zero, or non-numeric values mean 25; values below 1 are raised to 1 and values above 100 are lowered to 100. Send a positive integer; fractional values are not supported.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25},"PaymentId":{"name":"id","in":"path","required":true,"description":"Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations.","schema":{"$ref":"#/components/schemas/PaymentId"}},"BalanceCurrency":{"name":"currency","in":"query","required":false,"description":"Optional currency filter, trimmed and uppercased. Any three ASCII letters are accepted locally, not only payment-creation currencies. An unreported currency returns one zero-valued balance row. payoutGate is included only for omitted currency or PLN; currency= (empty) returns 400. Only the first value is used if repeated.","schema":{"type":"string","pattern":"^\\s*[A-Za-z]{3}\\s*$"},"example":"PLN"},"WebhookEventHeader":{"name":"X-Pstrykk-Event","in":"header","required":true,"description":"Must equal the JSON envelope type.","schema":{"type":"string","enum":["test","transaction","refund"]}},"WebhookDeliveryHeader":{"name":"X-Pstrykk-Delivery","in":"header","required":true,"description":"Must equal the JSON envelope id; stable across retries.","schema":{"$ref":"#/components/schemas/WebhookEventId"}},"WebhookTimestampHeader":{"name":"X-Pstrykk-Timestamp","in":"header","required":true,"description":"Unix seconds for this delivery attempt, included in the HMAC input. Check freshness.","schema":{"type":"string","pattern":"^[0-9]+$","example":"1915694400"}}},"headers":{"CacheControl":{"description":"All generated responses disable caching.","schema":{"type":"string","const":"no-store"}},"NoSniff":{"description":"Disable MIME-type sniffing.","schema":{"type":"string","const":"nosniff"}},"ContentLength":{"description":"Length of the binary, HTML, or raw-document response body in bytes.","schema":{"type":"integer","minimum":0}},"QrDisposition":{"description":"Payment QR only: inline filename built from the payment ID and selected extension. Not set by POST /v1/micro.","schema":{"type":"string","example":"inline; filename=\"ABCDEFGHIJKLMNOP.png\""}},"ContentSecurityPolicy":{"description":"SVG QR: default-src 'none'; style-src 'none'; sandbox. HTML docs: default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'. Not present on every representation.","schema":{"type":"string"}},"ReferrerPolicy":{"description":"Documentation HTML disables referrer disclosure.","schema":{"type":"string","const":"no-referrer"}},"ConnectionClose":{"description":"An oversized request body produces Connection: close.","schema":{"type":"string","const":"close"}}},"schemas":{"RequestKey":{"type":"string","description":"Client-generated UUID v4. Use a new key for each new operation and preserve its exact string on retries. Keys are not trimmed or case-normalized. Refund keys are merchant-wide across refund actions.","format":"uuid","pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-4[a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$","example":"7d444840-9dc0-4b7a-a2c0-11e13f4c6b37"},"PaymentId":{"type":"string","description":"Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations.","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]{1,64}$","example":"ABCDEFGHIJKLMNOP"},"PositiveAmount":{"type":"integer","description":"Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings.","minimum":1,"maximum":9007199254740991,"format":"int64","example":12500},"NonNegativeAmount":{"type":"integer","description":"Nonnegative integer in the relevant currency minor units.","minimum":0,"format":"int64","example":0},"CurrencyCode":{"type":"string","description":"Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation.","pattern":"^[A-Z]{3}$","example":"PLN"},"PaymentMethods":{"type":"object","properties":{"VIS":{"type":"boolean","description":"Visa. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"MSC":{"type":"boolean","description":"Mastercard. This is the public API code; other aliases are not accepted. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"AMX":{"type":"boolean","description":"American Express. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"JCB":{"type":"boolean","description":"JCB. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"DIN":{"type":"boolean","description":"Diners Club. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"DIS":{"type":"boolean","description":"Discover. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"CUP":{"type":"boolean","description":"UnionPay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"KLN":{"type":"boolean","description":"Klarna. Unavailable to affiliated individual accounts. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"BLI":{"type":"boolean","description":"BLIK. Available only for PLN payments. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"BANK":{"type":"boolean","description":"Pay by Bank. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"GPA":{"type":"boolean","description":"Google Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false},"APL":{"type":"boolean","description":"Apple Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied.","default":false}},"additionalProperties":false,"description":"Optional override of account payment-method preferences, not a merge. At least one flag must be true. Explicitly selecting any unavailable method returns 422; availability depends on the account and currency. If this object is omitted, stored preferences apply; without usable preferences all supported codes are considered, then unavailable methods are filtered out. Actual checkout availability is not guaranteed solely by these flags.","minProperties":1,"anyOf":[{"required":["VIS"],"properties":{"VIS":{"const":true}}},{"required":["MSC"],"properties":{"MSC":{"const":true}}},{"required":["AMX"],"properties":{"AMX":{"const":true}}},{"required":["JCB"],"properties":{"JCB":{"const":true}}},{"required":["DIN"],"properties":{"DIN":{"const":true}}},{"required":["DIS"],"properties":{"DIS":{"const":true}}},{"required":["CUP"],"properties":{"CUP":{"const":true}}},{"required":["KLN"],"properties":{"KLN":{"const":true}}},{"required":["BLI"],"properties":{"BLI":{"const":true}}},{"required":["BANK"],"properties":{"BANK":{"const":true}}},{"required":["GPA"],"properties":{"GPA":{"const":true}}},{"required":["APL"],"properties":{"APL":{"const":true}}}],"example":{"VIS":true,"MSC":true,"BLI":true}},"CreatePaymentRequest":{"type":"object","properties":{"redirectWebsite":{"type":["string","null"],"description":"Optional return website for this payment. For a new payment, omitting this field uses the account default; if no default website is configured, return is disabled. Explicit null, an empty string, or whitespace-only disables return for this payment. Leading and trailing whitespace are removed. Addresses without a protocol, such as test.pl or www.test.pl, receive https://; explicit http:// and https:// are preserved. Only valid HTTP(S) URLs without login or password are accepted. The trimmed input and normalized URL must not exceed 2048 characters. On the final success, rejection/cancellation, or expiry page, a return button and automatic redirect are available only when a return website is configured. The button allows immediate return. Redirecting is not proof of payment. The resolved website is stored with the payment; later account-default changes do not modify existing payments. When replaying requestKey, omitting this field preserves the previously stored website. Return to the store is disabled in embedded checkout, regardless of this setting.","examples":["https://www.test.pl/powrot","www.test.pl/powrot","test.pl/powrot","http://test.pl/powrot",null]},"redirectTime":{"anyOf":[{"type":"integer","minimum":1,"maximum":60},{"type":"string","pattern":"^\\s*0*(?:[1-9]|[1-5][0-9]|60)\\s*$"},{"type":"null"}],"description":"Optional automatic-return delay in seconds: an integer from 1 to 60 inclusive. A digit-only string, trimmed before validation, is also accepted in the same range. For a new payment, omitted or null uses the account default, with 10 seconds as the fallback. Effective only when a return website is configured. The delay starts on the final result page, not when the payment is created. Automatic return uses a server-supplied Refresh header and a JavaScript timer, followed by an HTTP redirect through the return endpoint. No countdown is displayed. The resolved delay is stored with the payment; later account-default changes do not modify existing payments. When replaying requestKey, omitted or null preserves the previously stored delay. Automatic return is disabled in embedded checkout, regardless of this setting.","examples":[10,60]},"requestKey":{"$ref":"#/components/schemas/RequestKey"},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"description":{"type":"string","description":"Payment description/title. Leading and trailing whitespace are removed; the resulting string must contain 1-450 Unicode code points.","minLength":1,"pattern":"\\S","example":"Order #2026-1042","x-normalized-max-length":450},"currency":{"type":["string","null"],"pattern":"^\\s*(?:[Pp][Ll][Nn]|[Ee][Uu][Rr])\\s*$","default":"PLN","description":"PLN or EUR. Trimmed and uppercased; omitted or null means PLN. For PLN the amount must be 500-600000 (5.00-6000.00 PLN), inclusive. No extra currency-specific amount bounds are imposed locally for EUR; payment-service restrictions can still apply.","example":"PLN"},"language":{"type":["string","null"],"pattern":"^\\s*(?:[Pp][Ll]|[Ss][Kk]|[Ee][Nn]|[Ii][Tt]|[Ff][Rr]|[Dd][Ee]|[Ee][Ss])\\s*$","description":"Checkout language. Explicit values: pl, sk, en, it, fr, de, es; trimmed and lowercased. Omitted or null defaults to pl. This field does not localize notification emails.","example":"en","x-default-when-omitted":"pl"},"expiresAt":{"type":["string","null"],"description":"Optional expiry with an explicit time zone, e.g. 2030-01-31T12:00:00Z or an offset such as +01:00. Input is trimmed and normalized to UTC. A NEW reservation requires at least 1 whole remaining second and at most 7776000 whole remaining seconds (90 days). Omitted or null uses the account default in hours, or 24 hours. Replays are not rejected merely because the original expiry has passed.","pattern":"^\\s*\\d{4}-\\d{2}-\\d{2}[Tt].*(?:[Zz]|[+-]\\d{2}:\\d{2})\\s*$"},"paymentMethods":{"$ref":"#/components/schemas/PaymentMethods"},"notificationEmail":{"type":["string","null"],"description":"Optional single notification recipient. Omitted, null, an empty string, or whitespace-only disables recipient notifications. The value is trimmed; a nonempty value must have at most 254 characters, exactly one @ with a dotted domain, and no whitespace, control characters, angle brackets, commas, semicolons, colons, quotes, parentheses, brackets, or backslashes. Notifications cover creation, settlement, and decline. Delivery is best-effort and a delivery error does not roll back payment creation. It is neither a webhook nor payer-account authentication. Notification content is Polish."}},"additionalProperties":true,"required":["requestKey","amountCents","description"],"description":"Creates a merchant-owned checkout link. Unknown top-level properties are ignored. Validation is applied before payment-creation replay lookup; a replay must still contain valid required fields.","allOf":[{"if":{"properties":{"currency":{"anyOf":[{"type":"null"},{"type":"string","pattern":"^\\s*[Pp][Ll][Nn]\\s*$"}]}}},"then":{"properties":{"amountCents":{"minimum":500,"maximum":600000}}}}]},"StatusHistoryEntry":{"type":"object","properties":{"statusId":{"type":["integer","null"],"description":"Stored numeric status identifier; no fixed ID-to-name map is guaranteed."},"status":{"type":["string","null"],"description":"Stored status label, preserved as recorded."},"changedAt":{"type":["string","null"],"description":"Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed."}},"additionalProperties":true,"required":["statusId","status","changedAt"],"description":"One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp."},"Payment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"description":{"type":"string","description":"Stored payment description/title."},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"language":{"type":"string","description":"Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist.","example":"en"},"status":{"type":["string","null"],"description":"Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized."},"statusId":{"type":["integer","null"],"description":"Current stored status identifier, or null. No stable numeric mapping is defined by these materials."},"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/StatusHistoryEntry"},"description":"Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status."},"createdAt":{"type":["string","null"],"format":"date-time","description":"Creation timestamp normalized to UTC, or null if unavailable/unparseable."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Requested link expiry; null if neither converts successfully."},"paidAt":{"type":["string","null"],"format":"date-time","description":"Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision."},"refundedCents":{"type":"integer","description":"Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds.","minimum":0,"format":"int64"},"refundableCents":{"type":"integer","description":"Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents.","minimum":0,"format":"int64"},"paymentUrl":{"type":"string","description":"Public pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active.","format":"uri","example":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP"},"linkActive":{"type":"boolean","description":"Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement."},"creationState":{"type":["string","null"],"description":"Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null.","example":"pending"},"creationError":{"type":["string","null"],"description":"Sanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code.","example":null}},"additionalProperties":true,"required":["id","description","amountCents","currency","language","status","statusId","statusHistory","createdAt","expiresAt","paidAt","refundedCents","refundableCents","paymentUrl","linkActive","creationState","creationError"],"description":"A merchant-owned payment view.","example":{"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null}},"SubscriptionId":{"type":"string","description":"Subscription identifier, separate from the first-payment transactionId. Newly generated IDs contain 16 uppercase ASCII letters. Lookup accepts 1-64 ASCII letters, digits, underscores, or hyphens.","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]{1,64}$","example":"QRSTUVWXYZABCDEF"},"CreateSubscriptionRequest":{"type":"object","description":"Creates a subscription: a first card payment followed by a recurring plan. Unknown top-level properties are ignored. Validation is applied before replay lookup; a replay must still contain valid required fields, including a future startingDate.","required":["requestKey","notificationEmail","subscriberName","description","amountCents","recurringAmountCents","monthsFrequency","totalPayments","startingDate"],"additionalProperties":true,"properties":{"requestKey":{"$ref":"#/components/schemas/RequestKey"},"notificationEmail":{"type":"string","description":"Required single recipient. Trimmed; at most 254 characters, exactly one @ with a dotted domain, and no whitespace, control characters, angle brackets, commas, semicolons, colons, quotes, parentheses, brackets, or backslashes. Receives the same first-payment notifications as notificationEmail in POST /v1/payments and, once the subscription first becomes Active, a one-time confirmation with the plan details and the subscription id. Content is Polish and delivery is best-effort. The address is not sent to the payment service, and the email field is hidden on the checkout page.","maxLength":254,"example":"customer@example.com"},"subscriberName":{"type":"string","description":"Subscriber name shown on the checkout page and in the confirmation email. Trimmed; 1-200 Unicode code points.","minLength":1,"pattern":"\\S","x-normalized-max-length":200,"example":"Jan Kowalski"},"description":{"type":"string","description":"Title of the first payment and the plan. Trimmed; 1-450 Unicode code points.","minLength":1,"pattern":"\\S","x-normalized-max-length":450,"example":"Premium plan"},"amountCents":{"allOf":[{"$ref":"#/components/schemas/PositiveAmount"}],"description":"First payment, charged at checkout, in minor units. Must be a JSON integer. For PLN 500-600000 (5.00-6000.00 PLN) inclusive; for EUR any positive safe integer, subject to payment-service limits. Can differ from recurringAmountCents.","example":4900},"recurringAmountCents":{"type":"integer","minimum":50,"maximum":250000,"format":"int64","description":"Amount of each recurring charge in minor units of the same currency, 50-250000 (0.50-2500.00) inclusive for both PLN and EUR. Must be a JSON integer.","example":4900},"monthsFrequency":{"anyOf":[{"type":"integer","minimum":1,"maximum":36},{"type":"string","pattern":"^\\s*\\d+\\s*$"}],"description":"Interval between recurring charges in months, 1-36 inclusive (1 = monthly, 3 = quarterly, 12 = yearly). A digit-only string is also accepted.","examples":[1,3,12]},"totalPayments":{"anyOf":[{"type":"integer","minimum":1,"maximum":999999},{"type":"string","pattern":"^\\s*\\d+\\s*$"}],"description":"Number of recurring charges after the first payment, 1-999999 inclusive. A digit-only string is also accepted.","examples":[12]},"startingDate":{"type":"string","pattern":"^\\s*\\d{2}-\\d{2}-\\d{4}\\s*$","description":"Date of the first recurring charge in dd-mm-yyyy format. Trimmed; must be a real calendar date whose 00:00 UTC is later than the current time, so in practice tomorrow (UTC) or later. Stored and returned as sent. Choose it after the expected first-payment date, typically one interval after today.","example":"15-02-2030"},"currency":{"type":["string","null"],"pattern":"^\\s*(?:[Pp][Ll][Nn]|[Ee][Uu][Rr])\\s*$","default":"PLN","description":"PLN or EUR for both the first payment and recurring charges. Trimmed and uppercased; omitted or null means PLN.","example":"PLN"},"language":{"type":["string","null"],"description":"Checkout language: pl, sk, en, it, fr, de, or es; trimmed and lowercased. Omitted or null means pl. The checkout heading and plan summary are localized; emails remain Polish.","example":"pl","x-default-when-omitted":"pl"},"expiresAt":{"type":["string","null"],"description":"Optional expiry of the first-payment checkout link with an explicit time zone, e.g. 2030-01-31T12:00:00Z. Normalized to UTC. A new reservation requires 1 second to 90 days from now. Omitted or null uses the store default in hours. On replay, omitted or null reuses the stored value. It does not limit the recurring plan.","pattern":"^\\s*\\d{4}-\\d{2}-\\d{2}[Tt].*(?:[Zz]|[+-]\\d{2}:\\d{2})\\s*$"},"redirectWebsite":{"type":["string","null"],"description":"Optional return website after the first-payment checkout. Same rules as redirectWebsite in POST /v1/payments: omitted uses the store default; null, empty, or whitespace disables return; replay without this field preserves the stored value.","examples":["https://www.test.pl/powrot",null]},"redirectTime":{"anyOf":[{"type":"integer","minimum":1,"maximum":60},{"type":"string","pattern":"^\\s*\\d+\\s*$"},{"type":"null"}],"description":"Optional automatic-return delay in seconds, 1-60. Same rules as redirectTime in POST /v1/payments: omitted or null uses the store default, then 10 seconds.","examples":[10]}}},"Subscription":{"type":"object","description":"Local subscription record. Status fields come from the payment service via background synchronization and can lag behind it.","required":["id","transactionId","subscriberName","description","notificationEmail","amountCents","recurringAmountCents","currency","language","monthsFrequency","startingDate","totalPayments","creationState","status","statusId","paymentsMade","lastChargeDate","nextChargeDate","cancelledAt","createdAt","paymentUrl"],"properties":{"id":{"$ref":"#/components/schemas/SubscriptionId"},"transactionId":{"allOf":[{"$ref":"#/components/schemas/PaymentId"}],"description":"ID of the first payment. Use it with GET /v1/payments/{id}, POST /v1/payments/{id}/sync, POST /v1/payments/{id}/refund, DELETE /v1/payments/{id}/link, and in transaction webhooks."},"storeId":{"type":["string","null"],"description":"Store that owns the subscription."},"subscriberName":{"type":"string"},"description":{"type":"string"},"notificationEmail":{"type":"string"},"amountCents":{"type":"integer","format":"int64","description":"First-payment amount in minor units."},"recurringAmountCents":{"type":"integer","format":"int64","description":"Amount of each recurring charge in minor units."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"language":{"type":"string","description":"Checkout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl."},"monthsFrequency":{"type":"integer","minimum":1,"maximum":36},"startingDate":{"type":"string","description":"First recurring-charge date as sent, dd-mm-yyyy.","example":"15-02-2030"},"totalPayments":{"type":"integer","minimum":1,"description":"Planned number of recurring charges after the first payment."},"creationState":{"type":["string","null"],"description":"Preparation of the first-payment checkout, separate from the financial status. creating or pending: in progress; ready: checkout prepared (not proof of payment); uncertain: outcome unconfirmed, keep the IDs and check GET /v1/payments/{transactionId}. Rejected creations are not returned.","examples":["creating","ready","uncertain"]},"status":{"type":["string","null"],"description":"Plan status reported by the payment service, e.g. Active or Cancelled; not a fixed enum. null until the first payment is paid and the plan is linked. For the first-payment status use GET /v1/payments/{transactionId}."},"statusId":{"type":["integer","null"],"description":"Numeric payment-service status ID. Do not hard-code mappings; use status."},"paymentsMade":{"type":["integer","null"],"description":"Number of plan charges made, as reported by the payment service; null until linked."},"lastChargeDate":{"type":["string","null"],"description":"Last plan charge. UTC ISO 8601 when convertible; otherwise the original stored value."},"nextChargeDate":{"type":["string","null"],"description":"Next scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value."},"cancelledAt":{"type":["string","null"],"format":"date-time","description":"Time when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status."},"createdAt":{"type":["string","null"],"format":"date-time"},"paymentUrl":{"type":"string","format":"uri","description":"Checkout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout."}}},"SubscriptionList":{"type":"object","required":["items","total","page","pageSize","pages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"total":{"type":"integer","minimum":0,"description":"Number of non-rejected subscriptions of the store."},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1,"maximum":100},"pages":{"type":"integer","minimum":1,"description":"Number of pages; at least 1, even when there are no items."}}},"CancelledSubscription":{"allOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"object","required":["cancelled"],"properties":{"cancelled":{"type":"boolean","const":true,"description":"Always true in a successful cancellation response."}}}]},"RefundRequest":{"type":"object","properties":{"requestKey":{"$ref":"#/components/schemas/RequestKey"},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"}},"additionalProperties":true,"required":["requestKey","amountCents"],"description":"Explicit full or partial refund amount in the original payment currency. There is no omit-amount/full-refund shortcut. Unknown properties are ignored."},"Refund":{"type":"object","properties":{"id":{"type":"string","description":"Locally generated refund-action UUID. Save this identifier for support/reconciliation.","format":"uuid"},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"state":{"type":"string","description":"The request has been accepted; this is not a statement that final settlement has completed.","enum":["accepted"]},"createdAt":{"type":"string","format":"date-time","description":"UTC timestamp when the refund reservation was created."},"message":{"type":"string","description":"Optional nonempty sanitized acceptance detail; not a stable machine-readable code."}},"additionalProperties":true,"required":["id","amountCents","currency","state","createdAt"]},"RefundResponse":{"type":"object","properties":{"refund":{"$ref":"#/components/schemas/Refund"},"payment":{"$ref":"#/components/schemas/Payment"}},"additionalProperties":true,"required":["refund","payment"],"description":"Accepted refund plus the updated local payment view."},"BalanceEntry":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/CurrencyCode"},"availableCents":{"type":"integer","description":"Available processing balance, in this currency minor units.","minimum":0,"format":"int64"},"pendingCents":{"type":"integer","description":"Pending processing balance, in this currency minor units.","minimum":0,"format":"int64"},"rollingReserveCents":{"type":"integer","description":"Collected merchant-risk reserve in this currency minor units. This is a held amount, not the full reserve target.","minimum":0,"format":"int64"},"securityDepositCents":{"type":"integer","description":"Collected contractual security deposit in this currency minor units. This is not available balance.","minimum":0,"format":"int64"}},"additionalProperties":true,"required":["currency","availableCents","pendingCents","rollingReserveCents","securityDepositCents"]},"PayoutGate":{"type":"object","properties":{"allowed":{"type":"boolean","description":"True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution."},"reason":{"type":["string","null"],"enum":["turnover","buffer",null],"description":"turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed."},"minPayoutCents":{"type":"integer","description":"Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal.","minimum":0,"format":"int64"},"turnoverCents":{"type":["integer","null"],"minimum":0,"description":"Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance."},"unlocksAt":{"type":["string","null"],"format":"date-time","description":"Recorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded."}},"additionalProperties":true,"required":["allowed","reason","minPayoutCents","turnoverCents","unlocksAt"],"description":"first-payout gate."},"BalanceResponse":{"type":"object","properties":{"balances":{"type":"array","items":{"$ref":"#/components/schemas/BalanceEntry"},"description":"All reported currencies, or exactly one zero-filled/actual entry if currency was supplied. No sort order is guaranteed."},"payoutGate":{"$ref":"#/components/schemas/PayoutGate"}},"additionalProperties":true,"required":["balances"],"description":"payoutGate is included only when currency is omitted or normalizes to PLN. It is omitted for a different currency filter. The unfiltered balances array can be empty."},"PayoutRequest":{"type":"object","properties":{"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"currency":{"type":["string","null"],"pattern":"^\\s*[Pp][Ll][Nn]\\s*$","default":"PLN","description":"Only PLN is accepted after trimming and uppercasing. Omitted or null also means PLN.","example":"PLN"}},"additionalProperties":true,"required":["amountCents"],"description":"PLN payout to the account-configured destination. No destination field or requestKey is consumed by this endpoint. Unknown properties, including an idempotency key, are ignored."},"PayoutResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true,"description":"The payout request returned an acceptance response; not final bank settlement."},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"currency":{"type":"string","description":"Payout currency.","enum":["PLN"]},"message":{"type":"string","description":"Sanitized message; defaults to Payout request accepted. if no nonempty message is returned."},"details":{"type":"object","additionalProperties":true,"description":"Optional sanitized additional response data. Its keys and nested shape are not a stable contract; it can contain a data field of varying type. Do not depend on a transaction or payout identifier being available."}},"additionalProperties":true,"required":["success","amountCents","currency","message"]},"QrOptions":{"type":"object","properties":{"size":{"type":"integer","description":"Required square image width/height in pixels. No default is applied. Some small but renderable images can still be difficult to scan.","minimum":64,"maximum":1024,"example":512},"format":{"type":"string","description":"Output image format. Trimmed and lowercased; use png or svg. This field, not Accept, selects the response representation.","pattern":"^\\s*(?:[Pp][Nn][Gg]|[Ss][Vv][Gg])\\s*$","example":"png"}},"additionalProperties":true,"required":["size","format"],"description":"QR rendering options. A small size may be accepted by validation but may not provide a practically scannable result for dense payloads. Unknown properties are ignored."},"TransferQrRequest":{"type":"object","properties":{"account":{"type":"string","description":"Polish bank account: valid 26-digit NRB, optionally prefixed with PL (case-insensitive). Whitespace and hyphens are removed before checksum validation. This is not limited to tax microaccounts; the endpoint does not verify recipient ownership.","example":"PL61109010140000071219812874"},"recipient":{"type":"string","description":"Recipient name. Trimmed length 1-20 Unicode code points; vertical bars and ASCII control characters are forbidden.","minLength":1,"pattern":"^[^|\\u0000-\\u001f\\u007f]+$","example":"Example Store","x-normalized-max-length":20},"title":{"type":"string","description":"Transfer title. Trimmed length 1-32 Unicode code points; vertical bars and ASCII control characters are forbidden.","minLength":1,"pattern":"^[^|\\u0000-\\u001f\\u007f]+$","example":"Order 2026-1042","x-normalized-max-length":32},"amountCents":{"type":"integer","description":"PLN transfer amount: 1-999999 minor units, inclusive (0.01-9999.99 PLN).","minimum":1,"maximum":999999,"example":12500},"nip":{"type":["string","null"],"description":"Optional valid Polish 10-digit tax identifier with checksum validation, optionally prefixed with PL. Whitespace and hyphens are removed and the prefix is case-insensitive. Omitted, null, or exactly the empty string disables it. A whitespace-only string is not treated as empty and fails validation."},"size":{"type":"integer","description":"Required square image width/height in pixels. No default is applied. Some small but renderable images can still be difficult to scan.","minimum":64,"maximum":1024,"example":512},"format":{"type":"string","description":"Output image format. Trimmed and lowercased; use png or svg. This field, not Accept, selects the response representation.","pattern":"^\\s*(?:[Pp][Nn][Gg]|[Ss][Vv][Gg])\\s*$","example":"png"}},"additionalProperties":true,"required":["account","recipient","title","amountCents","size","format"],"description":"Generate a Polish domestic bank-transfer QR payload using the ZBP Standard 2D structure. Currency is fixed to PLN, not selected by a currency field. The final payload cannot exceed 160 JavaScript string code units. No transfer is executed and no payment record is created."},"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"description":"The authenticated request reached the handler."}},"additionalProperties":true,"required":["ok"],"description":"Liveness indication only; does not verify payment-service reachability, bank availability, payout readiness, or end-to-end financial processing."},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code."},"id":{"$ref":"#/components/schemas/PaymentId"},"refundId":{"type":"string","description":"Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.","format":"uuid"},"availableCents":{"type":"integer","description":"Current available PLN balance reported for payout errors.","minimum":0,"format":"int64"},"payoutGate":{"$ref":"#/components/schemas/PayoutGate"}},"additionalProperties":true,"required":["error"],"description":"Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed."},"OpenApiDocument":{"type":"object","required":["openapi","info","paths"],"properties":{"openapi":{"type":"string","description":"OpenAPI specification version.","example":"3.1.0"},"info":{"type":"object","additionalProperties":true},"servers":{"type":"array","items":{"type":"object","additionalProperties":true}},"paths":{"type":"object","additionalProperties":true},"components":{"type":"object","additionalProperties":true}},"additionalProperties":true,"description":"The complete installed pstrykk OpenAPI JSON document."},"SyncRequest":{"type":"object","properties":{},"additionalProperties":true,"description":"Optional JSON object. Empty body and {} are accepted. All properties are ignored; no mutation options can be supplied."},"WebhookEventId":{"type":"string","description":"Stable event/delivery ID. Deduplicate by this value; retries retain it.","pattern":"^evt_([0-9a-f]{32}|test_[0-9a-f]{24})$","example":"evt_0123456789abcdef0123456789abcdef"},"WebhookTestData":{"type":"object","required":["message"],"properties":{"message":{"type":"string","const":"Testowy webhook pstrykk."}},"additionalProperties":true},"WebhookTransactionData":{"type":"object","required":["transactionId","requestKey","title","amountCents","currency","statusId","status","paymentDate","cancelledAt"],"properties":{"transactionId":{"$ref":"#/components/schemas/PaymentId"},"requestKey":{"type":["string","null"],"description":"Original payment request key; null when not available for imported/legacy records."},"title":{"type":["string","null"],"description":"Stored payment title; named title, not description, in this webhook."},"amountCents":{"type":["integer","null"],"minimum":0,"description":"Stored payment amount in integer minor units; null is retained for incomplete stored records."},"currency":{"type":["string","null"],"description":"Stored currency code, normally uppercase ISO 4217; null when unknown."},"statusId":{"type":["integer","null"],"description":"Original stored status identifier. No fixed numeric mapping is defined."},"status":{"type":["string","null"],"description":"Original stored payment status. Not restricted to a fixed enum. May be null for a local link-deactivation event."},"paymentDate":{"type":["string","null"],"description":"Stored payment-service payment date, not guaranteed to be normalized ISO 8601."},"cancelledAt":{"type":["string","null"],"format":"date-time","description":"Local link-deactivation timestamp or null. Not a remote cancellation or refund."}},"additionalProperties":true},"WebhookRefundData":{"type":"object","required":["refundId","transactionId","amountCents","currency","status"],"properties":{"refundId":{"type":"string","format":"uuid","description":"Local refund-action identifier, also returned as refund.id by an accepted API refund."},"transactionId":{"$ref":"#/components/schemas/PaymentId"},"amountCents":{"$ref":"#/components/schemas/PositiveAmount"},"currency":{"type":["string","null"],"description":"Payment currency for the refund, or null if not available in the stored payment record."},"status":{"type":"string","enum":["pending","accepted","rejected","unknown"],"description":"Local refund-action state: reserved, accepted request, rejected request, or unconfirmed outcome. accepted is not final settlement; unknown must not be bypassed by resubmission."}},"additionalProperties":true},"WebhookTestEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"$ref":"#/components/schemas/WebhookEventId"},"type":{"type":"string","const":"test"},"createdAt":{"type":"string","format":"date-time","description":"Original event creation time, retained on retries. Not a status ordering/version field."},"data":{"$ref":"#/components/schemas/WebhookTestData"}},"additionalProperties":true},"WebhookTransactionEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"$ref":"#/components/schemas/WebhookEventId"},"type":{"type":"string","const":"transaction"},"createdAt":{"type":"string","format":"date-time","description":"Original event creation time, retained on retries. Not a status ordering/version field."},"data":{"$ref":"#/components/schemas/WebhookTransactionData"}},"additionalProperties":true},"WebhookRefundEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"$ref":"#/components/schemas/WebhookEventId"},"type":{"type":"string","const":"refund"},"createdAt":{"type":"string","format":"date-time","description":"Original event creation time, retained on retries. Not a status ordering/version field."},"data":{"$ref":"#/components/schemas/WebhookRefundData"}},"additionalProperties":true},"WebhookEvent":{"oneOf":[{"$ref":"#/components/schemas/WebhookTestEvent"},{"$ref":"#/components/schemas/WebhookTransactionEvent"},{"$ref":"#/components/schemas/WebhookRefundEvent"}],"discriminator":{"propertyName":"type","mapping":{"test":"#/components/schemas/WebhookTestEvent","transaction":"#/components/schemas/WebhookTransactionEvent","refund":"#/components/schemas/WebhookRefundEvent"}}},"WebhookTestResponse":{"type":"object","required":["ok","url","statusCode","durationMs","error","responseBody","request"],"properties":{"ok":{"type":"boolean","description":"Whether the receiver returned an HTTP 2xx acknowledgement. HTTP 200 from this panel endpoint alone is not proof of delivery."},"url":{"type":"string","format":"uri","description":"Saved merchant receiver URL used for the attempt."},"statusCode":{"type":["integer","null"],"minimum":100,"maximum":599,"description":"Receiver HTTP response status, or null if no HTTP response was received."},"durationMs":{"type":"integer","minimum":0},"error":{"type":["string","null"],"description":"Delivery error or null. A non-2xx receiver status can produce ok=false with error=null; always inspect ok/statusCode."},"responseBody":{"type":"string","maxLength":4096,"description":"Receiver response text for display, possibly truncated. Not parsed as HTML or JSON."},"request":{"$ref":"#/components/schemas/WebhookTestEvent"}},"additionalProperties":true}},"responses":{"BadRequest":{"description":"Invalid URL, malformed JSON/object body, invalid field.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidJson":{"summary":"Malformed JSON","value":{"error":"Invalid JSON."}},"objectRequired":{"summary":"Top-level array, primitive, or null","value":{"error":"Request body must be a JSON object."}},"invalidUrl":{"summary":"URL parsing failed","value":{"error":"Invalid URL."}}}}}},"Unauthorized":{"description":"Missing, invalid, oversized, or repeated email/secret credentials.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid email or secret."}}}},"NotFound":{"description":"Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Payment not found."}}}},"Conflict":{"description":"Current state, account configuration, duplicate request data, or an uncertain financial outcome prevents this operation. Follow endpoint-specific recovery guidance; changing requestKey is not a safe universal retry strategy.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"accountSetup":{"summary":"Account not ready","value":{"error":"The account is not set up for payments yet."}},"uncertainCreation":{"summary":"Keep the payment ID and reconcile","value":{"error":"The result of creating payment ABCDEFGHIJKLMNOP could not be confirmed. Check GET /v1/payments/ABCDEFGHIJKLMNOP instead of creating a new payment.","id":"ABCDEFGHIJKLMNOP"}}}}}},"TooLarge":{"description":"JSON request body exceeded 65,536 bytes; the connection is closed.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Connection":{"$ref":"#/components/headers/ConnectionClose"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Request body is too large."}}}},"Unprocessable":{"description":"The syntactically valid operation was rejected, e.g. unavailable methods, amount over remaining balance/capacity, or payment-service business rejection.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"A selected payment method is not available for this payment."}}}},"InternalError":{"description":"Unexpected server error. For mutation requests, do not infer that no financial action occurred.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error."}}}},"PaymentServiceError":{"description":"Payment service unavailable, invalid/incomplete payment-service response, or data verification failed. A payout can be unconfirmed rather than rejected; consult endpoint guidance.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Could not fetch the payment status. Payment service is unavailable."}}}},"Unavailable":{"description":"concurrent payment-data change, or documentation file unavailable.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"concurrentStatus":{"summary":"Refresh before another state-dependent action","value":{"error":"The payment status was updated concurrently. Try again."}},"docsUnavailable":{"summary":"Unreadable or invalid installed JSON","value":{"error":"The documentation is temporarily unavailable."}}}}}}}},"x-tagGroups":[{"name":"Integration","tags":["Health","Payments","Payment links","Subscriptions","Refunds"]},{"name":"Funds","tags":["Balances","Payouts"]},{"name":"Assets and reference","tags":["QR codes","Documentation"]},{"name":"Webhook notifications","tags":["Webhooks"]}],"x-example-environment":{"PSTRYKK_API_BASE_URL":"Set to your deployment HTTPS origin without a trailing slash; do not assume the checkout origin also hosts the API.","PSTRYKK_EMAIL":"Merchant account email.","PSTRYKK_SECRET":"Original API secret kept in a trusted server-side environment."},"webhooks":{"test":{"summary":"Test notification to the merchant receiver","description":"Sent to the same merchant-configured webhook_url; this key is an event name, not a pstrykk HTTP route.","post":{"operationId":"receiveTestWebhook","tags":["Webhooks"],"summary":"Receive test notification","description":"Immediate one-shot delivery from the panel Test webhooka button. Uses the saved receiver URL and secret. No transaction/refund is created and no automatic retry is scheduled.\n\nVerify X-Pstrykk-Signature as sha256=HMAC_SHA256(webhook_secret, timestamp + \".\" + raw body), enforce timestamp freshness, and deduplicate by id. Return a completed 2xx response within 10 seconds. For transaction/refund, non-2xx or network failures use finite retries with 1/5/30-minute and 2/6/12/24-hour delays. Arrival order is not guaranteed. Examples are illustrative; null statusId deliberately avoids inventing a service status mapping.","security":[{"WebhookSignature":[]}],"parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEvent"},"example":{"id":"evt_test_0123456789abcdef01234567","type":"test","createdAt":"2030-09-15T12:00:00.000Z","data":{"message":"Testowy webhook pstrykk."}}}}},"responses":{"2XX":{"description":"The merchant receiver acknowledged delivery. Any completed HTTP 2xx response is accepted; the response body can be empty."},"default":{"description":"Unconfirmed delivery: non-2xx or connection failure. Redirects are not followed. Transaction/refund deliveries use finite retries; panel tests do not automatically retry."}}}},"transaction":{"summary":"Transaction notification to the merchant receiver","description":"Sent to the same merchant-configured webhook_url; this key is an event name, not a pstrykk HTTP route.","post":{"operationId":"receiveTransactionWebhook","tags":["Webhooks"],"summary":"Receive transaction notification","description":"Queued when a recorded payment status identifier/text changes or the local link is deactivated. Unchanged refreshes are suppressed. All stored status values are supported, with no fixed enum or numeric mapping. Local cancellation is indicated separately in cancelledAt. Only observed and stored changes can be reported; this is not a historical replay or a guarantee of all intermediate upstream states.\n\nVerify X-Pstrykk-Signature as sha256=HMAC_SHA256(webhook_secret, timestamp + \".\" + raw body), enforce timestamp freshness, and deduplicate by id. Return a completed 2xx response within 10 seconds. For transaction/refund, non-2xx or network failures use finite retries with 1/5/30-minute and 2/6/12/24-hour delays. Arrival order is not guaranteed. Examples are illustrative; null statusId deliberately avoids inventing a service status mapping.","security":[{"WebhookSignature":[]}],"parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTransactionEvent"},"example":{"id":"evt_0123456789abcdef0123456789abcdef","type":"transaction","createdAt":"2030-09-15T12:00:00.000Z","data":{"transactionId":"ABCDEFGHIJKLMNOP","requestKey":"7f0b76a9-67aa-47ac-91d1-a03541a13a54","title":"Order #1042","amountCents":12500,"currency":"PLN","statusId":null,"status":"Settled","paymentDate":"2030-09-15T11:59:00.000Z","cancelledAt":null}}}}},"responses":{"2XX":{"description":"The merchant receiver acknowledged delivery. Any completed HTTP 2xx response is accepted; the response body can be empty."},"default":{"description":"Unconfirmed delivery: non-2xx or connection failure. Redirects are not followed. Transaction/refund deliveries use finite retries; panel tests do not automatically retry."}}}},"refund":{"summary":"Refund notification to the merchant receiver","description":"Sent to the same merchant-configured webhook_url; this key is an event name, not a pstrykk HTTP route.","post":{"operationId":"receiveRefundWebhook","tags":["Webhooks"],"summary":"Receive refund notification","description":"Queued on insertion of a local refund action and on its state changes: pending, accepted, rejected, unknown. accepted confirms request acceptance, not final settlement. Final payment refund statuses are sent as separate transaction events. External refunds without a local action do not have a fabricated refund event.\n\nVerify X-Pstrykk-Signature as sha256=HMAC_SHA256(webhook_secret, timestamp + \".\" + raw body), enforce timestamp freshness, and deduplicate by id. Return a completed 2xx response within 10 seconds. For transaction/refund, non-2xx or network failures use finite retries with 1/5/30-minute and 2/6/12/24-hour delays. Arrival order is not guaranteed. Examples are illustrative; null statusId deliberately avoids inventing a service status mapping.","security":[{"WebhookSignature":[]}],"parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRefundEvent"},"example":{"id":"evt_fedcba9876543210fedcba9876543210","type":"refund","createdAt":"2030-09-15T12:00:00.000Z","data":{"refundId":"284b4b65-6ca6-44bf-824c-24d403ae9c6d","transactionId":"ABCDEFGHIJKLMNOP","amountCents":2500,"currency":"PLN","status":"accepted"}}}}},"responses":{"2XX":{"description":"The merchant receiver acknowledged delivery. Any completed HTTP 2xx response is accepted; the response body can be empty."},"default":{"description":"Unconfirmed delivery: non-2xx or connection failure. Redirects are not followed. Transaction/refund deliveries use finite retries; panel tests do not automatically retry."}}}}}}