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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
Responses
200 Authenticated liveness response.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Liveness indication only; does not verify payment-service reachability, bank availability, payout readiness, or end-to-end financial processing. |
(root).ok | boolean | yes | The authenticated request reached the handler. |
{
"ok": true
}400 Invalid URL, malformed JSON/object body, invalid field.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
Request body (required)
UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | allOf: any | no | Creates a merchant-owned checkout link. Unknown top-level properties are ignored. Validation is applied before payment-creation replay lookup; a replay must still contain valid required fields. |
(root).redirectWebsite | string | null | no | Optional return website for this payment. For a new payment, omitting this field uses the account default; if no default website is configured, return is disabled. Explicit null, an empty string, or whitespace-only disables return for this payment. Leading and trailing whitespace are removed. Addresses without a protocol, such as test.pl or www.test.pl, receive https://; explicit http:// and https:// are preserved. Only valid HTTP(S) URLs without login or password are accepted. The trimmed input and normalized URL must not exceed 2048 characters. On the final success, rejection/cancellation, or expiry page, a return button and automatic redirect are available only when a return website is configured. The button allows immediate return. Redirecting is not proof of payment. The resolved website is stored with the payment; later account-default changes do not modify existing payments. When replaying requestKey, omitting this field preserves the previously stored website. Return to the store is disabled in embedded checkout, regardless of this setting. |
(root).redirectTime | anyOf: integer | string | null | no | Optional automatic-return delay in seconds: an integer from 1 to 60 inclusive. A digit-only string, trimmed before validation, is also accepted in the same range. For a new payment, omitted or null uses the account default, with 10 seconds as the fallback. Effective only when a return website is configured. The delay starts on the final result page, not when the payment is created. Automatic return uses a server-supplied Refresh header and a JavaScript timer, followed by an HTTP redirect through the return endpoint. No countdown is displayed. The resolved delay is stored with the payment; later account-default changes do not modify existing payments. When replaying requestKey, omitted or null preserves the previously stored delay. Automatic return is disabled in embedded checkout, regardless of this setting. |
(root).redirectTime (anyOf[0]) | integer | no | minimum: 1; maximum: 60 |
(root).redirectTime (anyOf[1]) | string | no | pattern: ^\s*0*(?:[1-9]|[1-5][0-9]|60)\s*$ |
(root).redirectTime (anyOf[2]) | null | no | |
(root).requestKey | string (uuid) | yes | Client-generated UUID v4. Use a new key for each new operation and preserve its exact string on retries. Keys are not trimmed or case-normalized. Refund keys are merchant-wide across refund actions. — 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).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).description | string | yes | Payment description/title. Leading and trailing whitespace are removed; the resulting string must contain 1-450 Unicode code points. — minLength: 1; pattern: \S; example: Order #2026-1042 |
(root).currency | string | null | no | PLN or EUR. Trimmed and uppercased; omitted or null means PLN. For PLN the amount must be 500-600000 (5.00-6000.00 PLN), inclusive. No extra currency-specific amount bounds are imposed locally for EUR; payment-service restrictions can still apply. — pattern: ^\s*(?:[Pp][Ll][Nn]|[Ee][Uu][Rr])\s*$; default: PLN; example: PLN |
(root).language | string | null | no | Checkout language. Explicit values: pl, sk, en, it, fr, de, es; trimmed and lowercased. Omitted or null defaults to pl. This field does not localize notification emails. — pattern: ^\s*(?:[Pp][Ll]|[Ss][Kk]|[Ee][Nn]|[Ii][Tt]|[Ff][Rr]|[Dd][Ee]|[Ee][Ss])\s*$; example: en |
(root).expiresAt | string | null | no | Optional expiry with an explicit time zone, e.g. 2030-01-31T12:00:00Z or an offset such as +01:00. Input is trimmed and normalized to UTC. A NEW reservation requires at least 1 whole remaining second and at most 7776000 whole remaining seconds (90 days). Omitted or null uses the account default in hours, or 24 hours. Replays are not rejected merely because the original expiry has passed. — pattern: ^\s*\d{4}-\d{2}-\d{2}[Tt].*(?:[Zz]|[+-]\d{2}:\d{2})\s*$ |
(root).paymentMethods | anyOf: object | object | object | object | object | object | object | object | object | object | object | object | no | Optional override of account payment-method preferences, not a merge. At least one flag must be true. Explicitly selecting any unavailable method returns 422; availability depends on the account and currency. If this object is omitted, stored preferences apply; without usable preferences all supported codes are considered, then unavailable methods are filtered out. Actual checkout availability is not guaranteed solely by these flags. — example: {"VIS":true,"MSC":true,"BLI":true} |
(root).paymentMethods.VIS | boolean | no | Visa. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.MSC | boolean | no | Mastercard. This is the public API code; other aliases are not accepted. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.AMX | boolean | no | American Express. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.JCB | boolean | no | JCB. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.DIN | boolean | no | Diners Club. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.DIS | boolean | no | Discover. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.CUP | boolean | no | UnionPay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.KLN | boolean | no | Klarna. Unavailable to affiliated individual accounts. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.BLI | boolean | no | BLIK. Available only for PLN payments. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.BANK | boolean | no | Pay by Bank. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.GPA | boolean | no | Google Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.APL | boolean | no | Apple Pay. Enable this method for this payment; omitted flags are false when paymentMethods is explicitly supplied. — default: false |
(root).paymentMethods.VIS | any | yes | |
(root).paymentMethods.MSC | any | yes | |
(root).paymentMethods.AMX | any | yes | |
(root).paymentMethods.JCB | any | yes | |
(root).paymentMethods.DIN | any | yes | |
(root).paymentMethods.DIS | any | yes | |
(root).paymentMethods.CUP | any | yes | |
(root).paymentMethods.KLN | any | yes | |
(root).paymentMethods.BLI | any | yes | |
(root).paymentMethods.BANK | any | yes | |
(root).paymentMethods.GPA | any | yes | |
(root).paymentMethods.APL | any | yes | |
(root).notificationEmail | string | null | no | Optional single notification recipient. Omitted, null, an empty string, or whitespace-only disables recipient notifications. The value is trimmed; a nonempty value must have at most 254 characters, exactly one @ with a dotted domain, and no whitespace, control characters, angle brackets, commas, semicolons, colons, quotes, parentheses, brackets, or backslashes. Notifications cover creation, settlement, and decline. Delivery is best-effort and a delivery error does not roll back payment creation. It is neither a webhook nor payer-account authentication. Notification content is Polish. |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).description | string | yes | Stored payment description/title. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).statusHistory[].changedAt | string | null | yes | Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed. |
(root).createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).paymentUrl | string (uri) | yes | Public 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).linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).description | string | yes | Stored payment description/title. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).statusHistory[].changedAt | string | null | yes | Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed. |
(root).createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).paymentUrl | string (uri) | yes | Public 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).linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).description | string | yes | Stored payment description/title. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).statusHistory[].changedAt | string | null | yes | Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed. |
(root).createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).paymentUrl | string (uri) | yes | Public 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).linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Optional 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).description | string | yes | Stored payment description/title. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).statusHistory[].changedAt | string | null | yes | Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed. |
(root).createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).paymentUrl | string (uri) | yes | Public 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).linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Explicit full or partial refund amount in the original payment currency. There is no omit-amount/full-refund shortcut. Unknown properties are ignored. |
(root).requestKey | string (uuid) | yes | Client-generated UUID v4. Use a new key for each new operation and preserve its exact string on retries. Keys are not trimmed or case-normalized. Refund keys are merchant-wide across refund actions. — 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).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Accepted refund plus the updated local payment view. |
(root).refund | object | yes | |
(root).refund.id | string (uuid) | yes | Locally generated refund-action UUID. Save this identifier for support/reconciliation. |
(root).refund.amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).refund.currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).refund.state | enum(accepted) | yes | The request has been accepted; this is not a statement that final settlement has completed. |
(root).refund.createdAt | string (date-time) | yes | UTC timestamp when the refund reservation was created. |
(root).refund.message | string | no | Optional nonempty sanitized acceptance detail; not a stable machine-readable code. |
(root).payment | object | yes | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).payment.id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).payment.description | string | yes | Stored payment description/title. |
(root).payment.amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).payment.currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).payment.language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).payment.status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).payment.statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).payment.statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).payment.statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).payment.statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).payment.statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).payment.statusHistory[].changedAt | string | null | yes | Recorded 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.createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).payment.expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).payment.paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).payment.refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).payment.refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).payment.paymentUrl | string (uri) | yes | Public 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.linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).payment.creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).payment.creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
Responses
200 Locally deactivated payment; linkActive is false.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | A merchant-owned payment view. — example: {"id":"ABCDEFGHIJKLMNOP","description":"Order #2026-1042","amountCents":12500,"currency":"PLN","language":"en","status":null,"statusId":null,"statusHistory":[],"createdAt":"2030-01-15T10:00:00.000Z","expiresAt":"2030-01-16T10:00:00.000Z","paidAt":null,"refundedCents":0,"refundableCents":0,"paymentUrl":"https://pay.pstrykk.pl/ABCDEFGHIJKLMNOP","linkActive":true,"creationState":"ready","creationError":null} |
(root).id | string | yes | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).description | string | yes | Stored payment description/title. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Stored checkout language, with pl as the fallback for older or empty records. Responses are not restricted to the current explicit creation-language allowlist. — example: en |
(root).status | string | null | yes | Current stored payment status label, or null before one is available. Open-ended, service-supplied text; not an enum. A returned label is not necessarily freshly synchronized. |
(root).statusId | integer | null | yes | Current stored status identifier, or null. No stable numeric mapping is defined by these materials. |
(root).statusHistory | array of object | yes | Locally recorded history in insertion order. May be empty or incomplete and need not contain the current status. |
(root).statusHistory[] | object | no | One locally stored history entry. Entries are returned in insertion order, not resorted by timestamp. |
(root).statusHistory[].statusId | integer | null | yes | Stored numeric status identifier; no fixed ID-to-name map is guaranteed. |
(root).statusHistory[].status | string | null | yes | Stored status label, preserved as recorded. |
(root).statusHistory[].changedAt | string | null | yes | Recorded change timestamp, normally UTC ISO 8601. If conversion fails, the original stored value is returned; do not require date-time parsing to succeed. |
(root).createdAt | string | null (date-time) | yes | Creation timestamp normalized to UTC, or null if unavailable/unparseable. |
(root).expiresAt | string | null (date-time) | yes | Requested link expiry; null if neither converts successfully. |
(root).paidAt | string | null (date-time) | yes | Payment timestamp normalized to UTC; null if missing or not parseable. A nonnull timestamp alone is not a complete settlement decision. |
(root).refundedCents | integer (int64) | yes | Locally accepted refund total, capped at the original amount. This is not guaranteed to include externally initiated partial refunds. — minimum: 0 |
(root).refundableCents | integer (int64) | yes | Amount currently eligible for a new local refund, after accepted and pending/unconfirmed reservations. Zero unless the state is Settled, or a locally verifiable Partially refunded state, and no operation is unresolved. Use this field rather than amountCents minus refundedCents. — minimum: 0 |
(root).paymentUrl | string (uri) | yes | Public 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).linkActive | boolean | yes | Computed from locally stored data, not an availability guarantee. false is expected while creationState is pending and does not by itself mean cancellation or failure. true requires creationState ready, no local deactivation, an unexpired link, and an eligible stored payment status. Inspect creationState and creationError to distinguish preparation from failure. This field is not evidence of payment settlement. |
(root).creationState | string | null | yes | Local checkout-creation state, separate from the financial payment status: pending means preparation is in progress; ready means the checkout URL has been stored, not that payment has been received; rejected means creation failed; uncertain means the result is being reconciled without blindly resubmitting creation. Legacy records may contain other values or null. — example: pending |
(root).creationError | string | null | yes | Sanitized 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
page | query | integer | no | 1-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 |
pageSize | query | integer | no | Items per page. Missing, zero, or non-numeric values mean 25; values below 1 are raised to 1 and values above 100 are lowered to 100. Send a positive integer; fractional values are not supported. — minimum: 1; maximum: 100; default: 25 |
Responses
200 One page of subscriptions.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | |
(root).items | array of object | yes | |
(root).items[] | object | no | Local subscription record. Status fields come from the payment service via background synchronization and can lag behind it. |
(root).items[].id | string | yes | Subscription identifier, separate from the first-payment transactionId. Newly generated IDs contain 16 uppercase ASCII letters. Lookup accepts 1-64 ASCII letters, digits, underscores, or hyphens. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF |
(root).items[].transactionId | allOf: string | yes | ID of the first payment. Use it with GET /v1/payments/{id}, POST /v1/payments/{id}/sync, POST /v1/payments/{id}/refund, DELETE /v1/payments/{id}/link, and in transaction webhooks. |
(root).items[].storeId | string | null | no | Store that owns the subscription. |
(root).items[].subscriberName | string | yes | |
(root).items[].description | string | yes | |
(root).items[].notificationEmail | string | yes | |
(root).items[].amountCents | integer (int64) | yes | First-payment amount in minor units. |
(root).items[].recurringAmountCents | integer (int64) | yes | Amount of each recurring charge in minor units. |
(root).items[].currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).items[].language | string | yes | Checkout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl. |
(root).items[].monthsFrequency | integer | yes | minimum: 1; maximum: 36 |
(root).items[].startingDate | string | yes | First recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030 |
(root).items[].totalPayments | integer | yes | Planned number of recurring charges after the first payment. — minimum: 1 |
(root).items[].creationState | string | null | yes | Preparation of the first-payment checkout, separate from the financial status. creating or pending: in progress; ready: checkout prepared (not proof of payment); uncertain: outcome unconfirmed, keep the IDs and check GET /v1/payments/{transactionId}. Rejected creations are not returned. |
(root).items[].status | string | null | yes | Plan status reported by the payment service, e.g. Active or Cancelled; not a fixed enum. null until the first payment is paid and the plan is linked. For the first-payment status use GET /v1/payments/{transactionId}. |
(root).items[].statusId | integer | null | yes | Numeric payment-service status ID. Do not hard-code mappings; use status. |
(root).items[].paymentsMade | integer | null | yes | Number of plan charges made, as reported by the payment service; null until linked. |
(root).items[].lastChargeDate | string | null | yes | Last plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).items[].nextChargeDate | string | null | yes | Next scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).items[].cancelledAt | string | null (date-time) | yes | Time when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status. |
(root).items[].createdAt | string | null (date-time) | yes | |
(root).items[].paymentUrl | string (uri) | yes | Checkout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout. |
(root).total | integer | yes | Number of non-rejected subscriptions of the store. — minimum: 0 |
(root).page | integer | yes | minimum: 1 |
(root).pageSize | integer | yes | minimum: 1; maximum: 100 |
(root).pages | integer | yes | Number 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Creates a subscription: a first card payment followed by a recurring plan. Unknown top-level properties are ignored. Validation is applied before replay lookup; a replay must still contain valid required fields, including a future startingDate. |
(root).requestKey | string (uuid) | yes | Client-generated UUID v4. Use a new key for each new operation and preserve its exact string on retries. Keys are not trimmed or case-normalized. Refund keys are merchant-wide across refund actions. — 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).notificationEmail | string | yes | Required single recipient. Trimmed; at most 254 characters, exactly one @ with a dotted domain, and no whitespace, control characters, angle brackets, commas, semicolons, colons, quotes, parentheses, brackets, or backslashes. Receives the same first-payment notifications as notificationEmail in POST /v1/payments and, once the subscription first becomes Active, a one-time confirmation with the plan details and the subscription id. Content is Polish and delivery is best-effort. The address is not sent to the payment service, and the email field is hidden on the checkout page. — maxLength: 254; example: customer@example.com |
(root).subscriberName | string | yes | Subscriber 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).description | string | yes | Title of the first payment and the plan. Trimmed; 1-450 Unicode code points. — minLength: 1; pattern: \S; example: Premium plan |
(root).amountCents | allOf: integer (int64) | yes | First payment, charged at checkout, in minor units. Must be a JSON integer. For PLN 500-600000 (5.00-6000.00 PLN) inclusive; for EUR any positive safe integer, subject to payment-service limits. Can differ from recurringAmountCents. — example: 4900 |
(root).recurringAmountCents | integer (int64) | yes | Amount of each recurring charge in minor units of the same currency, 50-250000 (0.50-2500.00) inclusive for both PLN and EUR. Must be a JSON integer. — minimum: 50; maximum: 250000; example: 4900 |
(root).monthsFrequency | anyOf: integer | string | yes | Interval 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]) | integer | no | minimum: 1; maximum: 36 |
(root).monthsFrequency (anyOf[1]) | string | no | pattern: ^\s*\d+\s*$ |
(root).totalPayments | anyOf: integer | string | yes | Number of recurring charges after the first payment, 1-999999 inclusive. A digit-only string is also accepted. |
(root).totalPayments (anyOf[0]) | integer | no | minimum: 1; maximum: 999999 |
(root).totalPayments (anyOf[1]) | string | no | pattern: ^\s*\d+\s*$ |
(root).startingDate | string | yes | Date of the first recurring charge in dd-mm-yyyy format. Trimmed; must be a real calendar date whose 00:00 UTC is later than the current time, so in practice tomorrow (UTC) or later. Stored and returned as sent. Choose it after the expected first-payment date, typically one interval after today. — pattern: ^\s*\d{2}-\d{2}-\d{4}\s*$; example: 15-02-2030 |
(root).currency | string | null | no | PLN 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).language | string | null | no | Checkout language: pl, sk, en, it, fr, de, or es; trimmed and lowercased. Omitted or null means pl. The checkout heading and plan summary are localized; emails remain Polish. — example: pl |
(root).expiresAt | string | null | no | Optional expiry of the first-payment checkout link with an explicit time zone, e.g. 2030-01-31T12:00:00Z. Normalized to UTC. A new reservation requires 1 second to 90 days from now. Omitted or null uses the store default in hours. On replay, omitted or null reuses the stored value. It does not limit the recurring plan. — pattern: ^\s*\d{4}-\d{2}-\d{2}[Tt].*(?:[Zz]|[+-]\d{2}:\d{2})\s*$ |
(root).redirectWebsite | string | null | no | Optional return website after the first-payment checkout. Same rules as redirectWebsite in POST /v1/payments: omitted uses the store default; null, empty, or whitespace disables return; replay without this field preserves the stored value. |
(root).redirectTime | anyOf: integer | string | null | no | Optional automatic-return delay in seconds, 1-60. Same rules as redirectTime in POST /v1/payments: omitted or null uses the store default, then 10 seconds. |
(root).redirectTime (anyOf[0]) | integer | no | minimum: 1; maximum: 60 |
(root).redirectTime (anyOf[1]) | string | no | pattern: ^\s*\d+\s*$ |
(root).redirectTime (anyOf[2]) | null | no |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Local subscription record. Status fields come from the payment service via background synchronization and can lag behind it. |
(root).id | string | yes | Subscription identifier, separate from the first-payment transactionId. Newly generated IDs contain 16 uppercase ASCII letters. Lookup accepts 1-64 ASCII letters, digits, underscores, or hyphens. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF |
(root).transactionId | allOf: string | yes | ID of the first payment. Use it with GET /v1/payments/{id}, POST /v1/payments/{id}/sync, POST /v1/payments/{id}/refund, DELETE /v1/payments/{id}/link, and in transaction webhooks. |
(root).storeId | string | null | no | Store that owns the subscription. |
(root).subscriberName | string | yes | |
(root).description | string | yes | |
(root).notificationEmail | string | yes | |
(root).amountCents | integer (int64) | yes | First-payment amount in minor units. |
(root).recurringAmountCents | integer (int64) | yes | Amount of each recurring charge in minor units. |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Checkout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl. |
(root).monthsFrequency | integer | yes | minimum: 1; maximum: 36 |
(root).startingDate | string | yes | First recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030 |
(root).totalPayments | integer | yes | Planned number of recurring charges after the first payment. — minimum: 1 |
(root).creationState | string | null | yes | Preparation of the first-payment checkout, separate from the financial status. creating or pending: in progress; ready: checkout prepared (not proof of payment); uncertain: outcome unconfirmed, keep the IDs and check GET /v1/payments/{transactionId}. Rejected creations are not returned. |
(root).status | string | null | yes | Plan status reported by the payment service, e.g. Active or Cancelled; not a fixed enum. null until the first payment is paid and the plan is linked. For the first-payment status use GET /v1/payments/{transactionId}. |
(root).statusId | integer | null | yes | Numeric payment-service status ID. Do not hard-code mappings; use status. |
(root).paymentsMade | integer | null | yes | Number of plan charges made, as reported by the payment service; null until linked. |
(root).lastChargeDate | string | null | yes | Last plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).nextChargeDate | string | null | yes | Next scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).cancelledAt | string | null (date-time) | yes | Time when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status. |
(root).createdAt | string | null (date-time) | yes | |
(root).paymentUrl | string (uri) | yes | Checkout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout. |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Local subscription record. Status fields come from the payment service via background synchronization and can lag behind it. |
(root).id | string | yes | Subscription identifier, separate from the first-payment transactionId. Newly generated IDs contain 16 uppercase ASCII letters. Lookup accepts 1-64 ASCII letters, digits, underscores, or hyphens. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF |
(root).transactionId | allOf: string | yes | ID of the first payment. Use it with GET /v1/payments/{id}, POST /v1/payments/{id}/sync, POST /v1/payments/{id}/refund, DELETE /v1/payments/{id}/link, and in transaction webhooks. |
(root).storeId | string | null | no | Store that owns the subscription. |
(root).subscriberName | string | yes | |
(root).description | string | yes | |
(root).notificationEmail | string | yes | |
(root).amountCents | integer (int64) | yes | First-payment amount in minor units. |
(root).recurringAmountCents | integer (int64) | yes | Amount of each recurring charge in minor units. |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Checkout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl. |
(root).monthsFrequency | integer | yes | minimum: 1; maximum: 36 |
(root).startingDate | string | yes | First recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030 |
(root).totalPayments | integer | yes | Planned number of recurring charges after the first payment. — minimum: 1 |
(root).creationState | string | null | yes | Preparation of the first-payment checkout, separate from the financial status. creating or pending: in progress; ready: checkout prepared (not proof of payment); uncertain: outcome unconfirmed, keep the IDs and check GET /v1/payments/{transactionId}. Rejected creations are not returned. |
(root).status | string | null | yes | Plan status reported by the payment service, e.g. Active or Cancelled; not a fixed enum. null until the first payment is paid and the plan is linked. For the first-payment status use GET /v1/payments/{transactionId}. |
(root).statusId | integer | null | yes | Numeric payment-service status ID. Do not hard-code mappings; use status. |
(root).paymentsMade | integer | null | yes | Number of plan charges made, as reported by the payment service; null until linked. |
(root).lastChargeDate | string | null | yes | Last plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).nextChargeDate | string | null | yes | Next scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).cancelledAt | string | null (date-time) | yes | Time when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status. |
(root).createdAt | string | null (date-time) | yes | |
(root).paymentUrl | string (uri) | yes | Checkout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout. |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a subscription belonging to the authenticated merchant and the store bound to the credentials. This is the subscription id, not transactionId. Invalid, unknown, foreign-owned, other-store, or creation-rejected identifiers return 404. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF |
Responses
200 Cancellation confirmed by the payment service.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | allOf: object | object | no | |
(root).id | string | yes | Subscription identifier, separate from the first-payment transactionId. Newly generated IDs contain 16 uppercase ASCII letters. Lookup accepts 1-64 ASCII letters, digits, underscores, or hyphens. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: QRSTUVWXYZABCDEF |
(root).transactionId | allOf: string | yes | ID of the first payment. Use it with GET /v1/payments/{id}, POST /v1/payments/{id}/sync, POST /v1/payments/{id}/refund, DELETE /v1/payments/{id}/link, and in transaction webhooks. |
(root).storeId | string | null | no | Store that owns the subscription. |
(root).subscriberName | string | yes | |
(root).description | string | yes | |
(root).notificationEmail | string | yes | |
(root).amountCents | integer (int64) | yes | First-payment amount in minor units. |
(root).recurringAmountCents | integer (int64) | yes | Amount of each recurring charge in minor units. |
(root).currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).language | string | yes | Checkout language. Accurate in POST responses; GET /v1/subscriptions and DELETE responses currently always return pl. |
(root).monthsFrequency | integer | yes | minimum: 1; maximum: 36 |
(root).startingDate | string | yes | First recurring-charge date as sent, dd-mm-yyyy. — example: 15-02-2030 |
(root).totalPayments | integer | yes | Planned number of recurring charges after the first payment. — minimum: 1 |
(root).creationState | string | null | yes | Preparation of the first-payment checkout, separate from the financial status. creating or pending: in progress; ready: checkout prepared (not proof of payment); uncertain: outcome unconfirmed, keep the IDs and check GET /v1/payments/{transactionId}. Rejected creations are not returned. |
(root).status | string | null | yes | Plan status reported by the payment service, e.g. Active or Cancelled; not a fixed enum. null until the first payment is paid and the plan is linked. For the first-payment status use GET /v1/payments/{transactionId}. |
(root).statusId | integer | null | yes | Numeric payment-service status ID. Do not hard-code mappings; use status. |
(root).paymentsMade | integer | null | yes | Number of plan charges made, as reported by the payment service; null until linked. |
(root).lastChargeDate | string | null | yes | Last plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).nextChargeDate | string | null | yes | Next scheduled plan charge. UTC ISO 8601 when convertible; otherwise the original stored value. |
(root).cancelledAt | string | null (date-time) | yes | Time when cancellation was recorded locally (after DELETE or when synchronization first observed Cancelled). Reset to null if a later synchronization reports a different status. |
(root).createdAt | string | null (date-time) | yes | |
(root).paymentUrl | string (uri) | yes | Checkout link for the first payment, present immediately, even before creationState is ready. Use embedded.pstrykk.pl instead of pay.pstrykk.pl for embedded checkout. |
(root).cancelled | boolean | yes | Always 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
currency | query | string | no | Optional currency filter, trimmed and uppercased. Any three ASCII letters are accepted locally, not only payment-creation currencies. An unreported currency returns one zero-valued balance row. payoutGate is included only for omitted currency or PLN; currency= (empty) returns 400. Only the first value is used if repeated. — pattern: ^\s*[A-Za-z]{3}\s*$ |
Responses
200 Balances, plus payoutGate only for an unfiltered or PLN request.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | payoutGate is included only when currency is omitted or normalizes to PLN. It is omitted for a different currency filter. The unfiltered balances array can be empty. |
(root).balances | array of object | yes | All reported currencies, or exactly one zero-filled/actual entry if currency was supplied. No sort order is guaranteed. |
(root).balances[] | object | no | |
(root).balances[].currency | string | yes | Uppercase three-letter currency code in responses. A balance can report a currency not available for new payment creation. — pattern: ^[A-Z]{3}$; example: PLN |
(root).balances[].availableCents | integer (int64) | yes | Available processing balance, in this currency minor units. — minimum: 0 |
(root).balances[].pendingCents | integer (int64) | yes | Pending processing balance, in this currency minor units. — minimum: 0 |
(root).balances[].rollingReserveCents | integer (int64) | yes | Collected merchant-risk reserve in this currency minor units. This is a held amount, not the full reserve target. — minimum: 0 |
(root).balances[].securityDepositCents | integer (int64) | yes | Collected contractual security deposit in this currency minor units. This is not available balance. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
Request body (required)
UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | PLN payout to the account-configured destination. No destination field or requestKey is consumed by this endpoint. Unknown properties, including an idempotency key, are ignored. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | string | null | no | Only 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | |
(root).success | boolean | yes | The payout request returned an acceptance response; not final bank settlement. |
(root).amountCents | integer (int64) | yes | Positive integer in the relevant currency minor units, limited to Number.MAX_SAFE_INTEGER. Do not send decimal major-unit amounts or numeric strings. — minimum: 1; maximum: 9007199254740991; example: 12500 |
(root).currency | enum(PLN) | yes | Payout currency. |
(root).message | string | yes | Sanitized message; defaults to Payout request accepted. if no nonempty message is returned. |
(root).details | object | no | Optional sanitized additional response data. Its keys and nested shape are not a stable contract; it can contain a data field of varying type. Do not depend on a transaction or payout identifier being available. |
{
"success": true,
"amountCents": 50000,
"currency": "PLN",
"message": "Payout request accepted."
}400 Invalid URL, malformed JSON/object body, invalid field.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
id | path | string | yes | Identifier of a payment belonging to the authenticated merchant. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | QR rendering options. A small size may be accepted by validation but may not provide a practically scannable result for dense payloads. Unknown properties are ignored. |
(root).size | integer | yes | Required square image width/height in pixels. No default is applied. Some small but renderable images can still be difficult to scan. — minimum: 64; maximum: 1024; example: 512 |
(root).format | string | yes | Output image format. Trimmed and lowercased; use png or svg. This field, not Accept, selects the response representation. — pattern: ^\s*(?:[Pp][Nn][Gg]|[Ss][Vv][Gg])\s*$; example: png |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(value) | string (binary) | no | PNG file bytes; square size from the request. |
image/svg+xml
| Field | Type | Required | Description |
|---|---|---|---|
(value) | string (binary) | no | UTF-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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded. |
503 concurrent payment-data change, or documentation file unavailable.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | header | string | yes | Merchant account email. Required together with secret; exactly one occurrence. Nonblank, at most 254 characters before trimming; trimmed and lowercased. — minLength: 1; maxLength: 254 |
secret | header | string (password) | yes | Original opaque API secret, not its SHA-256 hash and not a Bearer token. Exactly one occurrence. Nonempty, maximum 1024 characters; not trimmed. Keep this value server-side. — minLength: 1; maxLength: 1024 |
Request body (required)
UTF-8 JSON object; maximum 65,536 received bytes. Unknown top-level fields are ignored.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Generate a Polish domestic bank-transfer QR payload using the ZBP Standard 2D structure. Currency is fixed to PLN, not selected by a currency field. The final payload cannot exceed 160 JavaScript string code units. No transfer is executed and no payment record is created. |
(root).account | string | yes | Polish bank account: valid 26-digit NRB, optionally prefixed with PL (case-insensitive). Whitespace and hyphens are removed before checksum validation. This is not limited to tax microaccounts; the endpoint does not verify recipient ownership. — example: PL61109010140000071219812874 |
(root).recipient | string | yes | Recipient name. Trimmed length 1-20 Unicode code points; vertical bars and ASCII control characters are forbidden. — minLength: 1; pattern: ^[^|\u0000-\u001f\u007f]+$; example: Example Store |
(root).title | string | yes | Transfer title. Trimmed length 1-32 Unicode code points; vertical bars and ASCII control characters are forbidden. — minLength: 1; pattern: ^[^|\u0000-\u001f\u007f]+$; example: Order 2026-1042 |
(root).amountCents | integer | yes | PLN transfer amount: 1-999999 minor units, inclusive (0.01-9999.99 PLN). — minimum: 1; maximum: 999999; example: 12500 |
(root).nip | string | null | no | Optional valid Polish 10-digit tax identifier with checksum validation, optionally prefixed with PL. Whitespace and hyphens are removed and the prefix is case-insensitive. Omitted, null, or exactly the empty string disables it. A whitespace-only string is not treated as empty and fails validation. |
(root).size | integer | yes | Required square image width/height in pixels. No default is applied. Some small but renderable images can still be difficult to scan. — minimum: 64; maximum: 1024; example: 512 |
(root).format | string | yes | Output image format. Trimmed and lowercased; use png or svg. This field, not Accept, selects the response representation. — pattern: ^\s*(?:[Pp][Nn][Gg]|[Ss][Vv][Gg])\s*$; example: png |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(value) | string (binary) | no | PNG file bytes; square size from the request. |
image/svg+xml
| Field | Type | Required | Description |
|---|---|---|---|
(value) | string (binary) | no | UTF-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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(value) | string | no | UTF-8 HTML document. |
400 Invalid URL, malformed JSON/object body, invalid field.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | The complete installed pstrykk OpenAPI JSON document. |
(root).openapi | string | yes | OpenAPI specification version. — example: 3.1.0 |
(root).info | object | yes | |
(root).servers | array of object | no | |
(root).servers[] | object | no | |
(root).paths | object | yes | |
(root).components | object | no |
400 Invalid URL, malformed JSON/object body, invalid field.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-CSRF-Token | header | string | yes | CSRF 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
| Field | Type | Required | Description |
|---|---|---|---|
(value) | object | no |
{}Responses
200 The test attempt finished. Check ok/statusCode to determine acknowledgement; remote failures also use this HTTP 200 response.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | |
(root).ok | boolean | yes | Whether the receiver returned an HTTP 2xx acknowledgement. HTTP 200 from this panel endpoint alone is not proof of delivery. |
(root).url | string (uri) | yes | Saved merchant receiver URL used for the attempt. |
(root).statusCode | integer | null | yes | Receiver HTTP response status, or null if no HTTP response was received. — minimum: 100; maximum: 599 |
(root).durationMs | integer | yes | minimum: 0 |
(root).error | string | null | yes | Delivery error or null. A non-2xx receiver status can produce ok=false with error=null; always inspect ok/statusCode. |
(root).responseBody | string | yes | Receiver response text for display, possibly truncated. Not parsed as HTML or JSON. — maxLength: 4096 |
(root).request | object | yes | |
(root).request.id | string | yes | Stable event/delivery ID. Deduplicate by this value; retries retain it. — pattern: ^evt_([0-9a-f]{32}|test_[0-9a-f]{24})$; example: evt_0123456789abcdef0123456789abcdef |
(root).request.type | string | yes | |
(root).request.createdAt | string (date-time) | yes | Original event creation time, retained on retries. Not a status ordering/version field. |
(root).request.data | object | yes | |
(root).request.data.message | string | yes |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded. |
403 Account inactive or invalid/missing panel CSRF token.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded. |
405 Only POST is supported.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded 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
| Field | Type | Required | Description |
|---|---|---|---|
(root) | object | no | Standard JSON error envelope. Additional fields depend on the endpoint and failure stage; none except error is universally guaranteed. |
(root).error | string | yes | Human-readable error text. It may contain sanitized contextual detail; do not parse it as a stable machine code. |
(root).id | string | no | Merchant-owned payment identifier. Newly generated IDs contain 16 uppercase ASCII letters. Lookup also accepts existing identifiers of 1-64 ASCII letters, digits, underscores, or hyphens. Invalid, unknown, or foreign-owned identifiers return 404. GET /v1/payments/{id} also exposes tracked rejected creations with creationState rejected and creationError; other payment operations can return 404 for rejected creations. — minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_-]{1,64}$; example: ABCDEFGHIJKLMNOP |
(root).refundId | string (uuid) | no | Refund-action identifier supplied for some duplicate, rejected, or uncertain refund outcomes. |
(root).availableCents | integer (int64) | no | Current available PLN balance reported for payout errors. — minimum: 0 |
(root).payoutGate | object | no | first-payout gate. |
(root).payoutGate.allowed | boolean | yes | True once the PLN turnover threshold has been recorded as exceeded and seven full 24-hour periods have elapsed. This field alone does not assert sufficient balance or successful payout execution. |
(root).payoutGate.reason | enum(turnover, buffer, null) | yes | turnover: threshold not recorded as exceeded; buffer: seven-day waiting period active; null: gate passed. |
(root).payoutGate.minPayoutCents | integer (int64) | yes | Configured first-payout gross-turnover threshold, expressed in PLN minor units. Turnover must be strictly greater, not merely equal. — minimum: 0 |
(root).payoutGate.turnoverCents | integer | null | yes | Calculated qualifying gross PLN turnover before the threshold has been recorded. Null on later calls. The response that first records threshold crossing can still contain the calculated integer. This is not the current balance. — minimum: 0 |
(root).payoutGate.unlocksAt | string | null (date-time) | yes | Recorded threshold-crossing timestamp plus seven full days; null before threshold crossing is recorded. |