> ## 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 # Integration > Basic payment link integration: create a product, add a subproduct and receive a link for a payment for anything. The basic integration scenario consists of two steps. **You create the product once**, then for each payment - no matter what it is for - you create a **subproduct**. The response contains a QR code with a link that redirects the payer to the payment page. All requests are authorized with an API key passed in the `X-API-KEY` header. Examples use the sandbox environment: `https://gateway-api.sandbox.paymove.io`. ## Step 1: Create a product The product represents your business in the Paymove system and is the container for subproducts (individual payments). You create it **only once**, at the start of 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": "Online Payments", "shortName": "PAYLINK", "location": "Warszawa", "timezone": "Europe/Warsaw" }' ``` | Field | Required | Description | | ------------- | -------- | ----------------------------------------- | | `partnerId` | Yes | Partner identifier (assigned by Paymove). | | `productType` | Yes | Product type - always `PAY`. | | `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": "Online Payments", "location": "Warszawa", "partner": { "id": "78562c79-2f5c-4415-8af4-c871eea92ef2", "name": "Nazwa Partnera Sp. z o.o.", "productTypes": ["PAY"] }, "timezone": "Europe/Warsaw", "shortName": "PAYLINK", "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`) you will use in step 2. ## Step 2: Create a subproduct (payment link) A subproduct represents a **single payment for anything** - a consultation, a booking, a membership fee, a repair, a phone order. In the URL, replace the product identifier (`productId`) received in step 1. In the `details` field you pass arbitrary key-value pairs describing what the payment is for - they are displayed to the payer on the payment page. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} curl --request POST \ --url https://gateway-api.sandbox.paymove.io/api/pay/product/d0a834f9-94a4-4b3a-aa10-27d911e3633f/subproduct \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \ --data '{ "externalId": "payment-2026-0001", "imageFormat": "png", "bannerType": "ticket", "price": 15000, "details": { "Payment title": "Online consultation - 60 minutes", "Paying for": "Advisory service", "Recipient": "Your Company Ltd.", "Payment no.": "payment-2026-0001" } }' ``` | Field | Required | Description | | ------------- | -------- | ---------------------------------------------------------------------------------------------- | | `externalId` | Yes | Payment identifier in your system. Displayed in the Paymove panel. | | `imageFormat` | Yes | QR code image format: `svg` or `png`. | | `bannerType` | Yes | Banner/card type (e.g. `ticket`) - affects the presentation. | | `price` | Yes | Amount in grosze (e.g. `15000` = 150.00 PLN). | | `details` | No | Arbitrary key-value pairs describing the payment - displayed to the payer on the payment page. | The values from `details` are displayed to the payer on the payment page - the key is the label and the value is the presented text. The payment can be for anything: describe it so the payer knows what they are paying for (e.g. "Payment title", "Paying for", "Recipient"). ## Response: QR code with the payment link The response (200) is the **binary content of an image** with the QR code in the format specified in `imageFormat` (SVG or PNG), returned with the `Content-Type: application/octet-stream` header. This 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 payment-link.png ``` The image is a ready-to-use banner with a QR code redirecting to the payment (for `png` e.g. 300x780 px). Send it by e-mail or SMS, put it on a printout or display it on a screen - after scanning (or clicking the link) the payer goes straight to paying the amount due. ## What's next? Add a webhook and receive automatic notifications about every completed payment. Full PAY API endpoint reference: pricing, forms, UI customization and webhooks.