> ## 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 # DocPay: basic integration > Basic DocPay integration: create a product, add a subproduct and receive a QR code that leads straight to payment. The basic DocPay integration scenario has two steps. **The product is created once**, then for each individual payment (e.g. a payment request) you create a **subproduct**. The response contains a QR code redirecting the customer to the payment page. All requests are authorized with an API key sent in the `X-API-KEY` header. Examples use the sandbox environment: `https://gateway-api.sandbox.paymove.io`. ## Step 1: Create product The product represents your service in the Paymove system and is a container for subproducts. You create it **only once**, when starting the integration. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} curl --request POST \ --url https://gateway-api.sandbox.paymove.io/api/product/pay \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \ --data '{ "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2", "productType": "PAY", "name": "Test Product", "shortName": "3456", "location": "Warsaw", "timezone": "Europe/Warsaw" }' ``` | Field | Required | Description | | ------------- | -------- | ----------------------------------------- | | `partnerId` | Yes | Partner identifier (assigned by Paymove). | | `productType` | Yes | Product type - always `PAY` for DocPay. | | `name` | Yes | Product name. | | `shortName` | Yes | Short display name. | | `location` | Yes | Location (e.g. city). | | `timezone` | Yes | IANA timezone (e.g. `Europe/Warsaw`). | **Response (200):** ```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} { "id": "d0a834f9-94a4-4b3a-aa10-27d911e3633f", "name": "Test Product", "location": "Warsaw", "partner": { "id": "78562c79-2f5c-4415-8af4-c871eea92ef2", "name": "Partner Name Sp. z o.o.", "productTypes": ["PAY"] }, "timezone": "Europe/Warsaw", "shortName": "3456", "emailEnabled": true, "smsEnabled": false, "fee": { "id": "01f9754e-78e3-4b2c-8186-d6862598a95a", "minimum": 30, "amount": 5, "fixed": false }, "productType": "PAY", "status": "ACTIVE", "creator": "PAYMOVE", "reviewEnabled": false, "createdAt": 1783245692.623763835, "updatedAt": 1783245692.623763835 } ``` The `id` field in the response is the product identifier (`productId`), which you will use in step 2. ## Step 2: Create subproduct A subproduct represents a **single payment** - e.g. one payment request. Replace the product identifier (`productId`) in the URL with the one received in step 1. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} curl --request POST \ --url https://gateway-api.sandbox.paymove.io/api/pay/product/1c32c81e-8f0e-40e1-8ad0-f5eeef9e3503/subproduct \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \ --data '{ "externalId": "test-external#2", "imageFormat": "svg", "bannerType": "ticket", "price": 25000, "details": { "Document no.": "test-external#2" } }' ``` | Field | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------- | | `externalId` | Yes | Document identifier in your system. Displayed in the Paymove panel as the document number. | | `imageFormat` | Yes | QR code image format: `svg` or `png`. | | `bannerType` | Yes | Banner/card type (e.g. `ticket`) - affects presentation. | | `price` | Yes | Amount in minor units (e.g. `25000` = 250.00 PLN). | | `details` | No | Key-value pairs displayed to the customer on the payment page (e.g. `"Document no.": "..."`). | Values from `details` are displayed to the user on the payment page - the key is the label, the value is the presented text. ## Response: QR code The response (200) is the **binary image content** with the QR code in the format set by `imageFormat` (SVG or PNG), returned with the `Content-Type: application/octet-stream` header. It is not JSON - save the response body directly to a file, e.g.: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} curl --request POST \ --url https://gateway-api.sandbox.paymove.io/api/pay/product/{productId}/subproduct \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \ --data '{ ... }' \ --output qr-code.svg ``` The image is a print-ready banner with a QR code redirecting to payment (for `png` e.g. 300x780 px). Place it e.g. on a payment request - after scanning, the customer goes directly to pay for the document. ## What's next? Full endpoint reference: pricing, forms, UI customization and webhooks (payment notifications).