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

# Changelog

> Paymove documentation changelog: new pages, API clarifications and fixes. Newest entries first.

This log covers changes to the documentation and to the integrations described here. The RSS feed is available at `/en/changelog/rss.xml`.

<Update label="7 October 2026" description="Payment button (widget)" tags={["Widget"]}>
  ### Payment button (widget)

  New [Payment button (widget)](/en/app-widget) section: a single `/v1/sdk.js` script that adds a floating button to your page and opens the payment process for your product in a modal. No backend and no API key - the product ID is all it needs.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> [Configuration](/en/app-widget/configuration) with `data-*` attributes: button text, bubble, language, position, several widgets on one page
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> [Controlling the widget](/en/app-widget/javascript-api) `window.PaymoveWidget`, the `paymove:completed` event and custom buttons
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Paying for a specific document (`data-external-id`) and a document-number entry screen (`data-document-entry`)
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> [Apple Pay activation](/en/app-widget/apple-pay): the widget requires `merchantDomain` on the product and a verification file from paymove hosted on your domain
</Update>

<Update label="25 September 2026" description="Payout account" tags={["API", "SDK", "DocPay"]}>
  ### Payout account (IBAN) on the product and the payment

  We documented how to choose the account Paymove pays funds out to. You set it when creating the product, and a single payment or subproduct can override it. Details: [REST API](/en/rest-api#payout-account-iban), [Configuration](/en/webhooks#1-create-a-product), [SDK](/en/sdk/javascript#payout-account) and [DocPay](/en/products/docpay/rest-api#payout-account-iban). The same information is in `skill.md`, `agents.md` and `llms.txt`.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> The `bankAccountDetails` object (`iban`, `holderName`, `nip` - only `iban` is required) when creating a product, a payment and a subproduct, also in the OpenAPI specifications
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> The `bankAccount` field of the SDK's `createPayment` - the IBAN alone as a string
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> An invalid IBAN returns `400`, and a product's account cannot be changed with `PATCH` - you can only set it at creation
</Update>

<Update label="24 September 2026" description="Payment methods" tags={["Payment methods", "AI agents"]}>
  ### Sandbox BLIK test code and PayPo minimum amount

  The [Payment methods](/en/payment-methods) page now explains how to pay in sandbox and from what amount the customer sees PayPo. The same information is in `skill.md`, `agents.md` and `llms.txt`.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Sandbox BLIK test code: any 6 digits starting with `777`, e.g. `777123`
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> PayPo appears on the checkout only from 10.00 PLN (`price` of `1000` or more) - below that the method is not listed
</Update>

<Update label="4 September 2026" description="Corrections" tags={["API", "Webhooks", "DocPay"]}>
  ### Corrections after verifying the docs against the API

  We went through the documentation endpoint by endpoint and checked every claim against the running API. Here is what needed correcting.

  * <span className="pm-change-fix"><Icon icon="wrench" size={14} /></span> `price` in the webhook payload is **the amount you sent when creating the payment**, not the amount net of the fee - you can compare it against your own record
  * <span className="pm-change-fix"><Icon icon="wrench" size={14} /></span> `retries` and `expectedCode` are **required** when registering a webhook; omitting either returns `500`
  * <span className="pm-change-fix"><Icon icon="wrench" size={14} /></span> The `details` field of a DocPay pricing entry is a **JSON object**, not a string
  * <span className="pm-change-fix"><Icon icon="wrench" size={14} /></span> The webhook list endpoint accepts only the `productId` parameter
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `CARD` added to the list of `details.triggerPayment` values in the OpenAPI specification
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> The `activeFrom` field in the webhook payload, plus `partnerId`, `productIds` and `retryOnCodes` on the webhook object
</Update>

<Update label="3 September 2026" description="Design" tags={["Docs"]}>
  ### New look for the documentation

  The documentation now uses the Paymove design system: light and dark themes, Google Sans Flex and Geist Mono typography, Lucide icons and redesigned components.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> New home page with quick links, products, popular pages and a prompt for AI assistants
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> **Changelog** tab with this log and an RSS feed
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Dark code blocks in both themes - syntax is always readable
</Update>

<Update label="3 September 2026" description="skill.md" tags={["AI agents", "API"]}>
  ### Clearer instructions for AI agents

  We updated `skill.md`, `agents.md` and `llms.txt` as well as the product and webhook configuration guide so an agent creates them correctly the first time.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Product field `metadata.logoUrl` - the shop logo shown on the checkout
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Product field descriptions: what is optional, what the customer sees, what lands in the webhook
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Error codes `401` (key lacks permissions) and `403` (foreign `partnerId`) on the [Error codes](/en/errors) page
</Update>

<Update label="1 September 2026" description="Apple Pay" tags={["Widget", "Payment methods"]}>
  ### Apple Pay in the widget

  In the modal the checkout runs in an iframe on your domain, so Apple requires that domain to be registered. The [Browser widget](/en/sdk/widget) page describes how.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> Product field `metadata.merchantDomain` and the Apple verification file
  * <span className="pm-change-warn"><Icon icon="triangle-alert" size={14} /></span> Without this configuration Apple Pay does not appear in the modal's payment methods
</Update>

<Update label="26 August 2026" description="autoclose" tags={["API", "Widget"]}>
  ### Automatic return to the shop

  The new `details.autoclose` field (milliseconds) makes the checkout return to `returnUrl` on its own after a successful payment, or close the modal in the widget. The countdown is shown in the “Back to shop” button and any customer interaction cancels it.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `details.autoclose` in the [REST API](/en/rest-api) and in SDK types from release `0.3.0`
  * <span className="pm-change-remove"><Icon icon="x" size={14} /></span> The widget's `autocloseDelay` option replaced by `autoclose` in the payment data
</Update>

<Update label="21 August 2026" description="Markdown" tags={["AI agents", "Docs"]}>
  ### Documentation for AI agents

  Every page can be fetched as plain Markdown, and an agent gets the complete integration procedure at a single URL.

  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `https://docs.paymove.io/skill.md` - step-by-step integration instructions for an agent
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> `agents.md` to paste into `AGENTS.md`, `CLAUDE.md` or Cursor rules, plus the `llms.txt` index
  * <span className="pm-change-add"><Icon icon="plus" size={14} /></span> New pages: [Quickstart](/en/quickstart), [Webhook signature verification](/en/webhook-signature), [Payment statuses](/en/payment-status), [Error codes](/en/errors)
</Update>

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

  The AI Payments section gained integration guides: the [MCP](/en/products/ai-payments/mcp) server for clients such as Claude Desktop or Claude Code and the [ElevenLabs voice agent](/en/products/ai-payments/elevenlabs).
</Update>

<Update label="6 August 2026" description="Naming" tags={["SDK", "API"]}>
  ### Naming change: merchant → product

  In the JavaScript SDK and the OpenAPI specification the term *merchant* was replaced with *product*. Payments are created within a product identified by `productId`.

  * <span className="pm-change-fix"><Icon icon="pencil" size={14} /></span> Unified names in the [SDK](/en/sdk/javascript) and the API reference
</Update>


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