> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paymove.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> ## paymove integration rules for AI agents
>
> These rules are verified against the live API. Follow them exactly.
>
> 1. Amounts are INTEGERS in grosze (minor units). `1000` means 10.00 PLN. PLN is the only supported currency and there is no currency field in the API.
> 2. A float `price` (e.g. `12.99`) is SILENTLY TRUNCATED to 12 grosze and still returns HTTP 200. Always send an integer: `Math.round(pln * 100)`.
> 3. Authenticate with the `X-API-KEY` header. Never `Authorization: Bearer`. Sandbox keys start with `sk_test_`, production keys with `sk_live_`.
> 4. Server-side only. A call from a merchant page is rejected. Never put the key in frontend code.
> 5. Unknown request fields are silently ignored and still return HTTP 200 - a wrong body shape looks like success. Match the documented shape exactly.
> 6. A missing `externalId` returns HTTP 500 `Something went wrong`, not 400. A missing `price` or `details.returnUrl` returns HTTP 200 and a usable `redirectUrl` - no error at all. Validate the body yourself before sending it.
> 7. Always verify the `X-Paymove-Signature` header on incoming webhooks before trusting them: https://docs.paymove.io/en/webhook-signature.md
> 8. Errors are `{"status": <int>, "message": "<text>"}`. Branch on the HTTP status only - never on `message`, which is unstable and leaks internal class names.
> 9. There is no rate limiting, no HTTP 429, no HTTP 422, no `Idempotency-Key` header and no API versioning. Do not write code that handles them.
> 10. Re-POSTing an `externalId` that already exists returns HTTP 200 with the ORIGINAL `redirectUrl` and silently discards EVERY field you send - the new price, description and details are all ignored. Use `PATCH /api/pay/product/{productId}/subproduct/{externalId}` to change a price.
> 11. Webhooks fire only on `COMPLETED` by default. Registering a webhook requires both `retries` and `expectedCode` - omitting either returns HTTP 500, and `retries: 0` means no retry at all. Delivery counts as successful when the HTTP status equals `expectedCode` - the response body is never inspected.
> 12. Never fulfil an order on the `returnUrl` redirect. The checkout does not redirect there by itself: the customer has to click "back to shop", and inside the widget modal that redirect never happens. Fulfil only in the webhook handler, after verifying the signature.
> 13. Do not pin a version of `@paymove-io/sdk` - install the latest.
> 14. If the merchant has no `productId` yet, do not stop at a placeholder: ask for the API key, the `partnerId` and the shop name, propose defaults for `location` and `timezone` (`Europe/Warsaw`), offer the optional fields once, then create the product for them with `POST /api/product/pay` and take `productId` from `id` in the response. Do the same for the webhook: register it, then assign it to the product. Guided procedure: https://docs.paymove.io/skill.md (Steps 1-2).
> 15. Full documentation index: https://docs.paymove.io/llms.txt · Copy-paste quickstart: https://docs.paymove.io/en/quickstart.md · Agent skill: https://docs.paymove.io/skill.md

# Zmiany

> Dziennik zmian dokumentacji Paymove: nowe strony, doprecyzowania w API i poprawki. Najnowsze wpisy na górze.

Ten dziennik opisuje zmiany w dokumentacji i w opisanych tu integracjach. Kanał RSS znajdziesz pod adresem `/changelog/rss.xml`.

<Update label="7 października 2026" description="Przycisk płatności (widget)" tags={["Widget"]}>
  ### Przycisk płatności (widget)

  Nowa sekcja [Przycisk płatności (widget)](/app-widget): jeden skrypt `/v1/sdk.js`, który dokłada do strony pływający przycisk i otwiera w modalu proces płatności za Twój produkt. Bez backendu i bez klucza API - wystarczy identyfikator produktu.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> [Konfiguracja](/app-widget/configuration) atrybutami `data-*`: tekst przycisku, dymek, język, położenie, kilka widgetów na stronie
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> [Sterowanie widgetem](/app-widget/javascript-api) `window.PaymoveWidget`, zdarzenie `paymove:completed` i własne przyciski
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Płatność za konkretny dokument (`data-external-id`) i ekran wpisania numeru dokumentu (`data-document-entry`)
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> [Aktywacja Apple Pay](/app-widget/apple-pay): w widgecie wymaga `merchantDomain` w produkcie i pliku weryfikacyjnego od paymove na Twojej domenie
</Update>

<Update label="25 września 2026" description="Rachunek do wypłat" tags={["API", "SDK", "DocPay"]}>
  ### Rachunek do wypłat (IBAN) przy produkcie i płatności

  Opisaliśmy, jak wskazać rachunek, na który Paymove wypłaca środki. Rachunek podajesz przy tworzeniu produktu, a pojedyncza płatność lub subprodukt mogą go nadpisać. Szczegóły: [REST API](/rest-api#rachunek-do-wypłaty-iban), [Konfiguracja](/webhooks#1-utworzenie-produktu), [SDK](/sdk/javascript#rachunek-do-wypłaty) i [DocPay](/products/docpay/rest-api#rachunek-do-wypłat-iban). Te same informacje trafiły do `skill.md`, `agents.md` i `llms.txt`.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Obiekt `bankAccountDetails` (`iban`, `holderName`, `nip` - wymagany tylko `iban`) przy tworzeniu produktu, płatności i subproduktu, także w specyfikacjach OpenAPI
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Pole `bankAccount` w `createPayment` SDK - sam IBAN jako tekst
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> Nieprawidłowy IBAN kończy się kodem `400`, a rachunku produktu nie zmienisz przez `PATCH` - ustawisz go wyłącznie przy tworzeniu
</Update>

<Update label="24 września 2026" description="Metody płatności" tags={["Metody płatności", "Agenci AI"]}>
  ### Testowy kod BLIK i minimalna kwota PayPo

  Na stronie [Metody płatności](/payment-methods) opisaliśmy, jak opłacić płatność w sandboxie i od jakiej kwoty klient widzi PayPo. Te same informacje trafiły do `skill.md`, `agents.md` i `llms.txt`.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Testowy kod BLIK w sandboxie: dowolne 6 cyfr zaczynające się od `777`, np. `777123`
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> PayPo pojawia się na checkoucie dopiero od 10,00 zł (`price` od `1000`) - przy niższej kwocie metody nie ma na liście
</Update>

<Update label="3 września 2026" description="Wygląd" tags={["Dokumentacja"]}>
  ### Nowa szata graficzna dokumentacji

  Dokumentacja korzysta teraz z design systemu Paymove: jasny i ciemny motyw, typografia Google Sans Flex i Geist Mono, ikony Lucide oraz przeprojektowane komponenty.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Nowa strona główna z szybkimi linkami, produktami, popularnymi stronami i promptem dla asystenta AI
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Zakładka **Zmiany** z tym dziennikiem i kanałem RSS
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Bloki kodu w ciemnym motywie w obu trybach - składnia zawsze czytelna
</Update>

<Update label="3 września 2026" description="skill.md" tags={["Agenci AI", "API"]}>
  ### Doprecyzowanie instrukcji dla agentów AI

  Zaktualizowaliśmy `skill.md`, `agents.md` i `llms.txt` oraz opis konfiguracji produktu i webhooka, tak aby agent tworzył je poprawnie za pierwszym razem.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Pole `metadata.logoUrl` produktu - logo sklepu wyświetlane na checkoucie
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Opis pól produktu: które są opcjonalne, co widzi klient, co trafia do webhooka
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Kody błędów `401` (brak uprawnień klucza) i `403` (obcy `partnerId`) na stronie [Kody błędów](/errors)
</Update>

<Update label="1 września 2026" description="Apple Pay" tags={["Widget", "Metody płatności"]}>
  ### Apple Pay w widgecie

  W modalu checkout działa w iframie na Twojej domenie, więc Apple wymaga jej rejestracji. Na stronie [Widget przeglądarkowy](/sdk/widget#apple-pay-w-modalu) opisaliśmy, jak to zrobić.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Pole `metadata.merchantDomain` produktu i plik weryfikacyjny Apple
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> Bez tej konfiguracji Apple Pay w modalu nie pojawi się na liście metod
</Update>

<Update label="26 sierpnia 2026" description="autoclose" tags={["API", "Widget"]}>
  ### Automatyczny powrót do sklepu

  Nowe pole `details.autoclose` (w milisekundach) sprawia, że po udanej płatności checkout sam wraca na `returnUrl`, a w widgecie zamyka modal. Odliczanie widać w przycisku „Wróć do sklepu”, a interakcja klienta je anuluje.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `details.autoclose` w [REST API](/rest-api) i w typach SDK od wydania `0.3.0`
  * <span className="pm-change-remove"><Icon icon="x" size={14} /></span> Opcja `autocloseDelay` widgetu zastąpiona przez `autoclose` w danych płatności
</Update>

<Update label="21 sierpnia 2026" description="Markdown" tags={["Agenci AI", "Dokumentacja"]}>
  ### Dokumentacja dla agentów AI

  Każdą stronę można pobrać jako czysty Markdown, a agent dostaje kompletną procedurę wdrożenia pod jednym adresem.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `https://docs.paymove.io/skill.md` - instrukcja wdrożenia krok po kroku dla agenta
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `agents.md` do wklejenia w `AGENTS.md`, `CLAUDE.md` lub reguły Cursora oraz indeks `llms.txt`
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Nowe strony: [Quickstart](/quickstart), [Weryfikacja podpisu webhooka](/webhook-signature), [Statusy płatności](/payment-status), [Kody błędów](/errors)
</Update>

<Update label="18 sierpnia 2026" description="MCP" tags={["AI Payments"]}>
  ### AI Payments: MCP i ElevenLabs

  Sekcja AI Payments dostała opisy integracji: serwer [MCP](/products/ai-payments/mcp) dla klientów takich jak Claude Desktop czy Claude Code oraz [agent głosowy ElevenLabs](/products/ai-payments/elevenlabs).
</Update>

<Update label="6 sierpnia 2026" description="Nazewnictwo" tags={["SDK", "API"]}>
  ### Zmiana nazewnictwa: merchant → product

  W SDK JavaScript i specyfikacji OpenAPI pojęcie *merchant* zastąpiliśmy *product*. Płatności tworzysz w ramach produktu identyfikowanego przez `productId`.

  * <span className="pm-change-fix"><Icon icon="pencil" size={14} /></span> Ujednolicone nazwy w [SDK](/sdk/javascript) i referencji API
</Update>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.