> ## 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": , "message": ""}`. 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, and `retries` defaults to `0` (no retries) unless you set it explicitly. 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. 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 # Zarejestruj webhook > Rejestruje webhook — adres URL po Twojej stronie, który Paymove wywołuje po zakończonej płatności. Po rejestracji webhook musi zostać przypisany do produktu osobnym wywołaniem. ## OpenAPI ````yaml /openapi-docpay.yaml post /api/pay/plugin/webhook openapi: 3.1.0 info: title: Paymove DocPay API version: 1.0.0 description: > API DocPay (PAY API) umożliwia przyjmowanie płatności za pojedyncze dokumenty — wezwania do zapłaty, bilety, faktury. Produkt tworzysz raz, a dla każdej płatności rejestrujesz subprodukt; w odpowiedzi otrzymujesz kod QR prowadzący do płatności. contact: name: Paymove Integration Team email: integration@paymove.io url: https://paymove.io servers: - url: https://gateway-api.sandbox.paymove.io description: Środowisko Sandbox (testowe) security: - ApiKeyAuth: [] tags: - name: Produkt description: Zarządzanie produktem (root modelu DocPay) - name: Subprodukty i kody QR description: Subprodukty i kody QR — jedna płatność za dokument - name: Cennik description: Cennik — opcje płatności dostępne dla klienta - name: Formularze description: Formularze zbierające dane od klientów (wersjonowane) - name: Personalizacja UI description: Personalizacja UI strony zakupu - name: Webhooki description: Powiadomienia o płatnościach paths: /api/pay/plugin/webhook: post: tags: - Webhooki summary: Zarejestruj webhook description: > Rejestruje webhook — adres URL po Twojej stronie, który Paymove wywołuje po zakończonej płatności. Po rejestracji webhook musi zostać przypisany do produktu osobnym wywołaniem. operationId: registerDocpayWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterWebhookRequest' example: name: PaymentSuccessHook endpoint: https://example.com/webhooks/payment-success method: POST requestTemplate: productId: productId event: event responseTemplate: status: ok expectedCode: 200 expectedResponse: '{ "status": "ok" }' retries: 3 partnerId: 78562c79-2f5c-4415-8af4-c871eea92ef2 type: PAYMENT headers: Authorization: - Bearer abc123 Content-Type: - application/json responses: '200': description: >- Webhook zarejestrowany — odpowiedź zawiera `id` (webhookId) oraz `signingSecret` content: application/json: schema: $ref: '#/components/schemas/Webhook' example: id: 18e19688-bdda-4843-8777-0f04d0143c77 name: PaymentSuccessHook endpoint: https://example.com/webhooks/payment-success method: POST requestTemplate: productId: productId event: event responseTemplate: status: ok expectedCode: 200 expectedResponse: '{ "status": "ok" }' retries: 3 type: PAYMENT headers: Authorization: - Bearer abc123 Content-Type: - application/json signingSecret: whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx components: schemas: RegisterWebhookRequest: type: object required: - name - endpoint - method - requestTemplate - expectedCode - partnerId - type properties: name: type: string example: PaymentSuccessHook endpoint: type: string format: uri description: URL, na który będą wysyłane powiadomienia method: type: string enum: - POST requestTemplate: type: object description: Szablon body żądania (zmienne podstawiane przez Paymove) responseTemplate: type: object description: Oczekiwana struktura odpowiedzi od partnera expectedCode: type: integer example: 200 expectedResponse: type: string example: '{ "status": "ok" }' retries: type: integer description: Liczba ponownych prób w przypadku niepowodzenia example: 3 partnerId: type: string format: uuid type: type: string enum: - PAYMENT headers: type: object additionalProperties: type: array items: type: string Webhook: type: object description: Obiekt webhooka zwracany przez API properties: id: type: string format: uuid description: Identyfikator webhooka (`webhookId`) name: type: string endpoint: type: string format: uri method: type: string requestTemplate: type: object responseTemplate: type: object expectedCode: type: integer expectedResponse: type: string retries: type: integer type: type: string headers: type: object additionalProperties: type: array items: type: string signingSecret: type: string description: >- Sekret do weryfikacji podpisu żądań przychodzących od Paymove — przechowuj bezpiecznie securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: | Klucz API dostarczony przez Paymove po zakończeniu procesu KYC. Przykład: `sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` ````