pstrykk API

Version 1.2.0

pstrykk API v1 Scope and compatibility This 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. Base URL Send 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. Embedded checkout (iframe) To 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. Authentication Every 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. Request and response conventions JSON 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. Payment creation and duplicate prevention POST /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. Refunds and payouts Refund 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. Statuses, polling, and links status 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. Errors and retry safety Errors 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. Subscriptions (recurring card payments) POST /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. Webhooks — merchant notifications (supplement) This 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. Configuration In 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–256 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. Types and payloads All 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. - test: data = {message}; message is the string "Testowy webhook pstrykk.". This verifies connectivity and does not create a transaction or refund. - 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. - 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. When events are created A 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. Signature and headers X-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. Acknowledgement, retries, and ordering A 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. Panel test The 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.

Servers: /

GET /v1/health

Check authenticated API liveness

Requires both authentication headers. Returns ok: true when this handler is reached. This is not a payment-service readiness test.

Parameters

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024

Responses

200 Authenticated liveness response.

application/json

FieldTypeRequiredDescription
(root)objectnoLiveness indication only; does not verify payment-service reachability, bank availability, payout readiness, or end-to-end financial processing.
(root).okbooleanyesThe authenticated request reached the handler.
{
  "ok": true
}

400 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 This route accepts GET only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/payments

Create or recover a payment link

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)allOf: anynoCreates 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.
(root).redirectWebsitestring | nullnoOptional 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.
(root).redirectTimeanyOf: integer | string | nullnoOptional 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.
(root).redirectTime (anyOf[0])integernominimum: 1; maximum: 60
(root).redirectTime (anyOf[1])stringnopattern: ^\s*0*(?:[1-9]|[1-5][0-9]|60)\s*$
(root).redirectTime (anyOf[2])nullno
(root).requestKeystring (uuid)yesClient-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. — 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
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).descriptionstringyesPayment 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
(root).currencystring | nullnoPLN 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. — pattern: ^\s*(?:[Pp][Ll][Nn]|[Ee][Uu][Rr])\s*$; default: PLN; example: PLN
(root).languagestring | nullnoCheckout 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. — pattern: ^\s*(?:[Pp][Ll]|[Ss][Kk]|[Ee][Nn]|[Ii][Tt]|[Ff][Rr]|[Dd][Ee]|[Ee][Ss])\s*$; example: en
(root).expiresAtstring | nullnoOptional 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*$
(root).paymentMethodsanyOf: object | object | object | object | object | object | object | object | object | object | object | objectnoOptional 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. — example: {"VIS":true,"MSC":true,"BLI":true}
(root).paymentMethods.VISbooleannoVisa. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.MSCbooleannoMastercard. 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
(root).paymentMethods.AMXbooleannoAmerican Express. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.JCBbooleannoJCB. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.DINbooleannoDiners Club. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.DISbooleannoDiscover. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.CUPbooleannoUnionPay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.KLNbooleannoKlarna. Unavailable to affiliated individual accounts. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.BLIbooleannoBLIK. Available only for PLN payments. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.BANKbooleannoPay by Bank. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.GPAbooleannoGoogle Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.APLbooleannoApple Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false
(root).paymentMethods.VISanyyes
(root).paymentMethods.MSCanyyes
(root).paymentMethods.AMXanyyes
(root).paymentMethods.JCBanyyes
(root).paymentMethods.DINanyyes
(root).paymentMethods.DISanyyes
(root).paymentMethods.CUPanyyes
(root).paymentMethods.KLNanyyes
(root).paymentMethods.BLIanyyes
(root).paymentMethods.BANKanyyes
(root).paymentMethods.GPAanyyes
(root).paymentMethods.APLanyyes
(root).notificationEmailstring | nullnoOptional 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.
{
  "requestKey": "7d444840-9dc0-4b7a-a2c0-11e13f4c6b37",
  "amountCents": 12500,
  "description": "Order #2026-1042",
  "language": "en"
}

Responses

201 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.

application/json

FieldTypeRequiredDescription
(root)objectnoA 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}
(root).idstringyesMerchant-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
(root).descriptionstringyesStored payment description/title.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesStored 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
(root).statusstring | nullyesCurrent 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.
(root).statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).refundableCentsinteger (int64)yesAmount 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
(root).paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).linkActivebooleanyesComputed 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.
(root).creationStatestring | nullyesLocal 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
(root).creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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
}

202 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.

application/json

FieldTypeRequiredDescription
(root)objectnoA 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}
(root).idstringyesMerchant-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
(root).descriptionstringyesStored payment description/title.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesStored 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
(root).statusstring | nullyesCurrent 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.
(root).statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).refundableCentsinteger (int64)yesAmount 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
(root).paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).linkActivebooleanyesComputed 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.
(root).creationStatestring | nullyesLocal 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
(root).creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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
}

400 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "requestKey must be a UUID v4."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "This requestKey belongs to different payment data.",
  "id": "ABCDEFGHIJKLMNOP"
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

422 No usable method, an explicitly unavailable method, or a payment-service business rejection. A rejected creation reservation cannot be replayed as a new attempt.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Select at least one payment method."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 Payment service unavailable, invalid/incomplete payment-service response, or data verification failed. A payout can be unconfirmed rather than rejected; consult endpoint guidance.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Could not fetch the payment status. Payment service is unavailable."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

GET /v1/payments/{id}

Read a payment with conditional refresh

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP

Responses

200 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.

application/json

FieldTypeRequiredDescription
(root)objectnoA 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}
(root).idstringyesMerchant-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
(root).descriptionstringyesStored payment description/title.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesStored 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
(root).statusstring | nullyesCurrent 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.
(root).statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).refundableCentsinteger (int64)yesAmount 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
(root).paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).linkActivebooleanyesComputed 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.
(root).creationStatestring | nullyesLocal 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
(root).creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment not found."
}

405 This route accepts GET only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The result of creating payment ABCDEFGHIJKLMNOP could not be confirmed yet. Try again shortly.",
  "id": "ABCDEFGHIJKLMNOP"
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/payments/{id}/sync

Force payment status synchronization

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP

Request body

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoOptional JSON object. Empty body and {} are accepted. All properties are ignored; no mutation options can be supplied.
{}

Responses

200 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.

application/json

FieldTypeRequiredDescription
(root)objectnoA 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}
(root).idstringyesMerchant-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
(root).descriptionstringyesStored payment description/title.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesStored 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
(root).statusstring | nullyesCurrent 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.
(root).statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).refundableCentsinteger (int64)yesAmount 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
(root).paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).linkActivebooleanyesComputed 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.
(root).creationStatestring | nullyesLocal 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
(root).creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment not found."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 The payment-service reference disagrees with the stored payment identity.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment identifier mismatch."
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

422 The syntactically valid operation was rejected, e.g. unavailable methods, amount over remaining balance/capacity, or payment-service business rejection.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "A selected payment method is not available for this payment."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 Payment-service network/authentication error or incomplete/unverifiable payment data. There is no success fallback to the stored payment.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Incomplete payment status received."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/payments/{id}/refund

Request a full or partial refund

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoExplicit full or partial refund amount in the original payment currency. There is no omit-amount/full-refund shortcut. Unknown properties are ignored.
(root).requestKeystring (uuid)yesClient-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. — 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
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
{
  "requestKey": "474f6a45-7a56-4e48-8d2a-75e38447e31a",
  "amountCents": 2500
}

Responses

200 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.

application/json

FieldTypeRequiredDescription
(root)objectnoAccepted refund plus the updated local payment view.
(root).refundobjectyes
(root).refund.idstring (uuid)yesLocally generated refund-action UUID. Save this identifier for support/reconciliation.
(root).refund.amountCentsinteger (int64)yesPositive 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; example: 12500
(root).refund.currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).refund.stateenum(accepted)yesThe request has been accepted; this is not a statement that final settlement has completed.
(root).refund.createdAtstring (date-time)yesUTC timestamp when the refund reservation was created.
(root).refund.messagestringnoOptional nonempty sanitized acceptance detail; not a stable machine-readable code.
(root).paymentobjectyesA 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}
(root).payment.idstringyesMerchant-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
(root).payment.descriptionstringyesStored payment description/title.
(root).payment.amountCentsinteger (int64)yesPositive 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; example: 12500
(root).payment.currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).payment.languagestringyesStored 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
(root).payment.statusstring | nullyesCurrent 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.
(root).payment.statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).payment.statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).payment.statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).payment.statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).payment.statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).payment.statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).payment.createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).payment.expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).payment.paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).payment.refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).payment.refundableCentsinteger (int64)yesAmount 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
(root).payment.paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).payment.linkActivebooleanyesComputed 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.
(root).payment.creationStatestring | nullyesLocal 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
(root).payment.creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment not found."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 Duplicate, nonrefundable state, unverifiable previous partial refunds, or an unresolved financial result. Do not change the key to bypass an uncertain refund.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "This operation has already been submitted. Do not submit it again.",
  "refundId": "284b4b65-6ca6-44bf-824c-24d403ae9c6d"
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

422 Amount exceeds remaining refundable capacity, or the refund/status service returned a definite rejection. refundId may be included, but is not guaranteed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "amountCents exceeds the refundable amount (10000)."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 Payment service unavailable, invalid/incomplete payment-service response, or data verification failed. A payout can be unconfirmed rather than rejected; consult endpoint guidance.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Could not fetch the payment status. Payment service is unavailable."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

DELETE /v1/payments/{id}/link

Deactivate an unpaid checkout link locally

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP

Responses

200 Locally deactivated payment; linkActive is false.

application/json

FieldTypeRequiredDescription
(root)objectnoA 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}
(root).idstringyesMerchant-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
(root).descriptionstringyesStored payment description/title.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesStored 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
(root).statusstring | nullyesCurrent 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.
(root).statusIdinteger | nullyesCurrent stored status identifier, or null. No stable numeric mapping is defined by these materials.
(root).statusHistoryarray of objectyesLocally recorded history in insertion order. May be empty or incomplete and need not contain the current status.
(root).statusHistory[]objectnoOne locally stored history entry. Entries are returned in insertion order, not resorted by timestamp.
(root).statusHistory[].statusIdinteger | nullyesStored numeric status identifier; no fixed ID-to-name map is guaranteed.
(root).statusHistory[].statusstring | nullyesStored status label, preserved as recorded.
(root).statusHistory[].changedAtstring | nullyesRecorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed.
(root).createdAtstring | null (date-time)yesCreation timestamp normalized to UTC, or null if unavailable/unparseable.
(root).expiresAtstring | null (date-time)yesRequested link expiry; null if neither converts successfully.
(root).paidAtstring | null (date-time)yesPayment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision.
(root).refundedCentsinteger (int64)yesLocally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0
(root).refundableCentsinteger (int64)yesAmount 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
(root).paymentUrlstring (uri)yesPublic pstrykk checkout URL; always constructed as https://pay.pstrykk.pl/{id}. Its presence does not mean the link is active. — example: https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP
(root).linkActivebooleanyesComputed 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.
(root).creationStatestring | nullyesLocal 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
(root).creationErrorstring | nullyesSanitized failure detail when creationState is rejected; otherwise null. Human-readable text, not a stable machine-readable error code. — example: null
{
  "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 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment not found."
}

405 This route accepts DELETE only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 Previously deactivated link, unresolved operation, or a status that is no longer eligible for local deactivation.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment link is already deactivated."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

GET /v1/subscriptions

List subscriptions

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
pagequeryintegerno1-based page number. Missing, zero, negative, or non-numeric values mean 1. Send a positive integer; fractional values are not supported. — minimum: 1; default: 1
pageSizequeryintegernoItems 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. — minimum: 1; maximum: 100; default: 25

Responses

200 One page of subscriptions.

application/json

FieldTypeRequiredDescription
(root)objectno
(root).itemsarray of objectyes
(root).items[]objectnoLocal subscription record. Status fields come from the payment service via background synchronization and can lag behind it.
(root).items[].idstringyesSubscription 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
(root).items[].transactionIdallOf: stringyesID 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.
(root).items[].storeIdstring | nullnoStore that owns the subscription.
(root).items[].subscriberNamestringyes
(root).items[].descriptionstringyes
(root).items[].notificationEmailstringyes
(root).items[].amountCentsinteger (int64)yesFirst-payment amount in minor units.
(root).items[].recurringAmountCentsinteger (int64)yesAmount of each recurring charge in minor units.
(root).items[].currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).items[].languagestringyesCheckout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl.
(root).items[].monthsFrequencyintegeryesminimum: 1; maximum: 36
(root).items[].startingDatestringyesFirst recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030
(root).items[].totalPaymentsintegeryesPlanned number of recurring charges after the first payment. — minimum: 1
(root).items[].creationStatestring | nullyesPreparation 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.
(root).items[].statusstring | nullyesPlan 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}.
(root).items[].statusIdinteger | nullyesNumeric payment-service status ID. Do not hard-code mappings; use status.
(root).items[].paymentsMadeinteger | nullyesNumber of plan charges made, as reported by the payment service; null until linked.
(root).items[].lastChargeDatestring | nullyesLast plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).items[].nextChargeDatestring | nullyesNext scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).items[].cancelledAtstring | null (date-time)yesTime when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status.
(root).items[].createdAtstring | null (date-time)yes
(root).items[].paymentUrlstring (uri)yesCheckout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout.
(root).totalintegeryesNumber of non-rejected subscriptions of the store. — minimum: 0
(root).pageintegeryesminimum: 1
(root).pageSizeintegeryesminimum: 1; maximum: 100
(root).pagesintegeryesNumber of pages; at least 1, even when there are no items. — minimum: 1
{
  "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 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 Methods other than GET and POST. The Allow header currently lists only GET, although POST is also supported on this path.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

POST /v1/subscriptions

Create or recover a subscription

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields, including paymentMethods, are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoCreates 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.
(root).requestKeystring (uuid)yesClient-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. — 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
(root).notificationEmailstringyesRequired 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
(root).subscriberNamestringyesSubscriber name shown on the checkout page and in the confirmation email. Trimmed; 1-200 Unicode code points. — minLength: 1; pattern: \S; example: Jan Kowalski
(root).descriptionstringyesTitle of the first payment and the plan. Trimmed; 1-450 Unicode code points. — minLength: 1; pattern: \S; example: Premium plan
(root).amountCentsallOf: integer (int64)yesFirst 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
(root).recurringAmountCentsinteger (int64)yesAmount 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. — minimum: 50; maximum: 250000; example: 4900
(root).monthsFrequencyanyOf: integer | stringyesInterval between recurring charges in months, 1-36 inclusive (1 = monthly, 3 = quarterly, 12 = yearly). A digit-only string is also accepted.
(root).monthsFrequency (anyOf[0])integernominimum: 1; maximum: 36
(root).monthsFrequency (anyOf[1])stringnopattern: ^\s*\d+\s*$
(root).totalPaymentsanyOf: integer | stringyesNumber of recurring charges after the first payment, 1-999999 inclusive. A digit-only string is also accepted.
(root).totalPayments (anyOf[0])integernominimum: 1; maximum: 999999
(root).totalPayments (anyOf[1])stringnopattern: ^\s*\d+\s*$
(root).startingDatestringyesDate 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. — pattern: ^\s*\d{2}-\d{2}-\d{4}\s*$; example: 15-02-2030
(root).currencystring | nullnoPLN or EUR for both the first payment and recurring charges. Trimmed and uppercased; omitted or null means PLN. — pattern: ^\s*(?:[Pp][Ll][Nn]|[Ee][Uu][Rr])\s*$; default: PLN; example: PLN
(root).languagestring | nullnoCheckout 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
(root).expiresAtstring | nullnoOptional 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*$
(root).redirectWebsitestring | nullnoOptional 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.
(root).redirectTimeanyOf: integer | string | nullnoOptional 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.
(root).redirectTime (anyOf[0])integernominimum: 1; maximum: 60
(root).redirectTime (anyOf[1])stringnopattern: ^\s*\d+\s*$
(root).redirectTime (anyOf[2])nullno
{
  "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"
}

Responses

201 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.

application/json

FieldTypeRequiredDescription
(root)objectnoLocal subscription record. Status fields come from the payment service via background synchronization and can lag behind it.
(root).idstringyesSubscription 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
(root).transactionIdallOf: stringyesID 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.
(root).storeIdstring | nullnoStore that owns the subscription.
(root).subscriberNamestringyes
(root).descriptionstringyes
(root).notificationEmailstringyes
(root).amountCentsinteger (int64)yesFirst-payment amount in minor units.
(root).recurringAmountCentsinteger (int64)yesAmount of each recurring charge in minor units.
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesCheckout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl.
(root).monthsFrequencyintegeryesminimum: 1; maximum: 36
(root).startingDatestringyesFirst recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030
(root).totalPaymentsintegeryesPlanned number of recurring charges after the first payment. — minimum: 1
(root).creationStatestring | nullyesPreparation 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.
(root).statusstring | nullyesPlan 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}.
(root).statusIdinteger | nullyesNumeric payment-service status ID. Do not hard-code mappings; use status.
(root).paymentsMadeinteger | nullyesNumber of plan charges made, as reported by the payment service; null until linked.
(root).lastChargeDatestring | nullyesLast plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).nextChargeDatestring | nullyesNext scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).cancelledAtstring | null (date-time)yesTime when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status.
(root).createdAtstring | null (date-time)yes
(root).paymentUrlstring (uri)yesCheckout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout.
{
  "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"
}

202 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.

application/json

FieldTypeRequiredDescription
(root)objectnoLocal subscription record. Status fields come from the payment service via background synchronization and can lag behind it.
(root).idstringyesSubscription 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
(root).transactionIdallOf: stringyesID 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.
(root).storeIdstring | nullnoStore that owns the subscription.
(root).subscriberNamestringyes
(root).descriptionstringyes
(root).notificationEmailstringyes
(root).amountCentsinteger (int64)yesFirst-payment amount in minor units.
(root).recurringAmountCentsinteger (int64)yesAmount of each recurring charge in minor units.
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesCheckout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl.
(root).monthsFrequencyintegeryesminimum: 1; maximum: 36
(root).startingDatestringyesFirst recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030
(root).totalPaymentsintegeryesPlanned number of recurring charges after the first payment. — minimum: 1
(root).creationStatestring | nullyesPreparation 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.
(root).statusstring | nullyesPlan 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}.
(root).statusIdinteger | nullyesNumeric payment-service status ID. Do not hard-code mappings; use status.
(root).paymentsMadeinteger | nullyesNumber of plan charges made, as reported by the payment service; null until linked.
(root).lastChargeDatestring | nullyesLast plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).nextChargeDatestring | nullyesNext scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).cancelledAtstring | null (date-time)yesTime when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status.
(root).createdAtstring | null (date-time)yes
(root).paymentUrlstring (uri)yesCheckout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout.
{
  "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"
}

400 Invalid request body or field. Validation also applies to replays.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "requestKey must be a UUID v4."
}

401 Missing, invalid, oversized, or repeated email/secret credentials, or the store bound to the credentials is no longer active.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

409 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "This requestKey belongs to different subscription data.",
  "id": "ABCDEFGHIJKLMNOP"
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

DELETE /v1/subscriptions/{id}

Cancel a subscription

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF

Responses

200 Cancellation confirmed by the payment service.

application/json

FieldTypeRequiredDescription
(root)allOf: object | objectno
(root).idstringyesSubscription 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
(root).transactionIdallOf: stringyesID 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.
(root).storeIdstring | nullnoStore that owns the subscription.
(root).subscriberNamestringyes
(root).descriptionstringyes
(root).notificationEmailstringyes
(root).amountCentsinteger (int64)yesFirst-payment amount in minor units.
(root).recurringAmountCentsinteger (int64)yesAmount of each recurring charge in minor units.
(root).currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).languagestringyesCheckout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl.
(root).monthsFrequencyintegeryesminimum: 1; maximum: 36
(root).startingDatestringyesFirst recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030
(root).totalPaymentsintegeryesPlanned number of recurring charges after the first payment. — minimum: 1
(root).creationStatestring | nullyesPreparation 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.
(root).statusstring | nullyesPlan 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}.
(root).statusIdinteger | nullyesNumeric payment-service status ID. Do not hard-code mappings; use status.
(root).paymentsMadeinteger | nullyesNumber of plan charges made, as reported by the payment service; null until linked.
(root).lastChargeDatestring | nullyesLast plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).nextChargeDatestring | nullyesNext scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value.
(root).cancelledAtstring | null (date-time)yesTime when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status.
(root).createdAtstring | null (date-time)yes
(root).paymentUrlstring (uri)yesCheckout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout.
(root).cancelledbooleanyesAlways true in a successful cancellation response.
{
  "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 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Invalid, unknown, foreign-owned, other-store, or creation-rejected subscription identifier.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Subscription not found."
}

405 This route accepts DELETE only; there is no single-subscription GET.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Brak UUID operatora. Anulowanie nie zostało wykonane; pierwsza płatność może nadal być aktywna."
}

422 The payment service rejected the cancellation.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request failed (HTTP 422)."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 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.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Operator nie potwierdził anulowania. Ponów sprawdzenie."
}

GET /v1/balance

Read balances and first-payout eligibility

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
currencyquerystringnoOptional 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. — pattern: ^\s*[A-Za-z]{3}\s*$

Responses

200 Balances, plus payoutGate only for an unfiltered or PLN request.

application/json

FieldTypeRequiredDescription
(root)objectnopayoutGate 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.
(root).balancesarray of objectyesAll reported currencies, or exactly one zero-filled/actual entry if currency was supplied. No sort order is guaranteed.
(root).balances[]objectno
(root).balances[].currencystringyesUppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN
(root).balances[].availableCentsinteger (int64)yesAvailable processing balance, in this currency minor units. — minimum: 0
(root).balances[].pendingCentsinteger (int64)yesPending processing balance, in this currency minor units. — minimum: 0
(root).balances[].rollingReserveCentsinteger (int64)yesCollected merchant-risk reserve in this currency minor units. This is a held amount, not the full reserve target. — minimum: 0
(root).balances[].securityDepositCentsinteger (int64)yesCollected contractual security deposit in this currency minor units. This is not available balance. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "balances": [
    {
      "currency": "PLN",
      "availableCents": 70000,
      "pendingCents": 5000,
      "rollingReserveCents": 0,
      "securityDepositCents": 0
    }
  ],
  "payoutGate": {
    "allowed": false,
    "reason": "turnover",
    "minPayoutCents": 100000,
    "turnoverCents": 75000,
    "unlocksAt": null
  }
}

400 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 This route accepts GET only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 Account is not payment-enabled.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The account is not set up for payments yet."
}

422 The syntactically valid operation was rejected, e.g. unavailable methods, amount over remaining balance/capacity, or payment-service business rejection.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "A selected payment method is not available for this payment."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 Payment service unavailable, invalid/incomplete payment-service response, or data verification failed. A payout can be unconfirmed rather than rejected; consult endpoint guidance.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Could not fetch the payment status. Payment service is unavailable."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/balance/payout

Request a PLN payout

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoPLN payout to the account-configured destination. No destination field or requestKey is consumed by this endpoint. Unknown properties, including an idempotency key, are ignored.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencystring | nullnoOnly PLN is accepted after trimming and uppercasing. Omitted or null also means PLN. — pattern: ^\s*[Pp][Ll][Nn]\s*$; default: PLN; example: PLN
{
  "amountCents": 50000,
  "currency": "PLN"
}

Responses

200 Payout request accepted; additional details are optional and have no stable schema.

application/json

FieldTypeRequiredDescription
(root)objectno
(root).successbooleanyesThe payout request returned an acceptance response; not final bank settlement.
(root).amountCentsinteger (int64)yesPositive 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; example: 12500
(root).currencyenum(PLN)yesPayout currency.
(root).messagestringyesSanitized message; defaults to Payout request accepted. if no nonempty message is returned.
(root).detailsobjectnoOptional 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.
{
  "success": true,
  "amountCents": 50000,
  "currency": "PLN",
  "message": "Payout request accepted."
}

400 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 First-payout gate is not yet passed, or the account/threshold configuration is invalid. Gate rejection includes payoutGate and availableCents.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The first payout is not available yet.",
  "payoutGate": {
    "allowed": false,
    "reason": "turnover",
    "minPayoutCents": 100000,
    "turnoverCents": 75000,
    "unlocksAt": null
  },
  "availableCents": 70000
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

422 Amount exceeds available PLN funds or a definite payout/payment-service business rejection occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "amountCents exceeds the available balance.",
  "availableCents": 40000
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

502 Service failure or unconfirmed payout result. A payout may have been accepted even though this response is an error; do not blindly retry.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The result of the payout could not be confirmed. Check your balance before retrying."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/payments/{id}/qr

Generate a payment-link QR image

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024
idpathstringyesIdentifier 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. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoQR 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.
(root).sizeintegeryesRequired 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
(root).formatstringyesOutput 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
{
  "size": 512,
  "format": "png"
}

Responses

200 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.

image/png

FieldTypeRequiredDescription
(value)string (binary)noPNG file bytes; square size from the request.

image/svg+xml

FieldTypeRequiredDescription
(value)string (binary)noUTF-8 SVG image; square size from the request.

400 Invalid request JSON/object body, missing/invalid size or format, or QR capacity/rendering failure.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "size must be an integer between 64 and 1024 (pixels)."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

404 Payment not found, invalid payment identifier, foreign-owned payment, creation-rejected payment, or unknown endpoint.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Payment not found."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

409 Payment creation is not ready, no checkout URL is stored, or the local link is inactive.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment is not ready yet."
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

500 Other unexpected errors use the same envelope.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

POST /v1/micro

Generate a Polish bank-transfer QR image

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

NameInTypeRequiredDescription
emailheaderstringyesMerchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254
secretheaderstring (password)yesOriginal 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. — minLength: 1; maxLength: 1024

Request body (required)

UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.

application/json

FieldTypeRequiredDescription
(root)objectnoGenerate 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.
(root).accountstringyesPolish 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
(root).recipientstringyesRecipient 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
(root).titlestringyesTransfer 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
(root).amountCentsintegeryesPLN transfer amount: 1-999999 minor units, inclusive (0.01-9999.99 PLN). — minimum: 1; maximum: 999999; example: 12500
(root).nipstring | nullnoOptional 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.
(root).sizeintegeryesRequired 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
(root).formatstringyesOutput 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
{
  "account": "PL61109010140000071219812874",
  "recipient": "Example Store",
  "title": "Order 2026-1042",
  "amountCents": 12500,
  "size": 512,
  "format": "png"
}

Responses

200 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.

image/png

FieldTypeRequiredDescription
(value)string (binary)noPNG file bytes; square size from the request.

image/svg+xml

FieldTypeRequiredDescription
(value)string (binary)noUTF-8 SVG image; square size from the request.

400 Malformed JSON/object body, invalid QR options, invalid account/NIP checksum, invalid transfer text, or amount outside the fixed PLN limits.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "size must be an integer between 64 and 1024 (pixels)."
}

401 Missing, invalid, oversized, or repeated email/secret credentials.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid email or secret."
}

405 This route accepts POST only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

413 JSON request body exceeded 65,536 bytes; the connection is closed.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Request body is too large."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 concurrent payment-data change, or documentation file unavailable.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The payment status was updated concurrently. Try again."
}

GET /v1/docs

Open the public HTML documentation

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 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.

text/html

FieldTypeRequiredDescription
(value)stringnoUTF-8 HTML document.

400 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

405 This public route accepts GET only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 The installed documentation file is missing, unreadable, invalid JSON, or not a JSON object.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The documentation is temporarily unavailable."
}

GET /v1/openapi

Download the installed OpenAPI JSON

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 The original installed OpenAPI document bytes.

application/json

FieldTypeRequiredDescription
(root)objectnoThe complete installed pstrykk OpenAPI JSON document.
(root).openapistringyesOpenAPI specification version. — example: 3.1.0
(root).infoobjectyes
(root).serversarray of objectno
(root).servers[]objectno
(root).pathsobjectyes
(root).componentsobjectno

400 Invalid URL, malformed JSON/object body, invalid field.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Invalid JSON."
}

405 This public route accepts GET only.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Method not allowed."
}

500 Unexpected server error. For mutation requests, do not infer that no financial action occurred.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "Internal server error."
}

503 The installed documentation file is missing, unreadable, invalid JSON, or not a JSON object.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.
{
  "error": "The documentation is temporarily unavailable."
}

POST /api/panel/webhook-test

Send a test webhook from the authenticated panel

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.

Parameters

NameInTypeRequiredDescription
X-CSRF-TokenheaderstringyesCSRF token of the authenticated panel session, read from panel-csrf in the panel HTML. — minLength: 1

Request body

The panel sends {}. The endpoint uses stored configuration and does not read override fields from the request body.

application/json

FieldTypeRequiredDescription
(value)objectno
{}

Responses

200 The test attempt finished. Check ok/statusCode to determine acknowledgement; remote failures also use this HTTP 200 response.

application/json

FieldTypeRequiredDescription
(root)objectno
(root).okbooleanyesWhether the receiver returned an HTTP 2xx acknowledgement. HTTP 200 from this panel endpoint alone is not proof of delivery.
(root).urlstring (uri)yesSaved merchant receiver URL used for the attempt.
(root).statusCodeinteger | nullyesReceiver HTTP response status, or null if no HTTP response was received. — minimum: 100; maximum: 599
(root).durationMsintegeryesminimum: 0
(root).errorstring | nullyesDelivery error or null. A non-2xx receiver status can produce ok=false with error=null; always inspect ok/statusCode.
(root).responseBodystringyesReceiver response text for display, possibly truncated. Not parsed as HTML or JSON. — maxLength: 4096
(root).requestobjectyes
(root).request.idstringyesStable event/delivery ID. Deduplicate by this value; retries retain it. — pattern: ^evt_([0-9a-f]{32}|test_[0-9a-f]{24})$; example: evt_0123456789abcdef0123456789abcdef
(root).request.typestringyes
(root).request.createdAtstring (date-time)yesOriginal event creation time, retained on retries. Not a status ordering/version field.
(root).request.dataobjectyes
(root).request.data.messagestringyes
{
  "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 Missing/expired panel session or missing user.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.

403 Account inactive or invalid/missing panel CSRF token.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.

405 Only POST is supported.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.

422 Save both a receiver URL and a webhook secret before testing.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.

429 Another test was requested less than five seconds ago for this user in this server process.

application/json

FieldTypeRequiredDescription
(root)objectnoStandard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed.
(root).errorstringyesHuman-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code.
(root).idstringnoMerchant-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
(root).refundIdstring (uuid)noRefund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes.
(root).availableCentsinteger (int64)noCurrent available PLN balance reported for payout errors. — minimum: 0
(root).payoutGateobjectnofirst-payout gate.
(root).payoutGate.allowedbooleanyesTrue 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.
(root).payoutGate.reasonenum(turnover, buffer, null)yesturnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed.
(root).payoutGate.minPayoutCentsinteger (int64)yesConfigured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0
(root).payoutGate.turnoverCentsinteger | nullyesCalculated 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. — minimum: 0
(root).payoutGate.unlocksAtstring | null (date-time)yesRecorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded.