REST API

PAY API (DocPay) endpoint reference: product, subproduct and QR codes, pricing, forms, UI customization and webhooks. The basic integration scenario (product + subproduct) is described in the Tutorial.

1. Product

The product represents your service in the Paymove system and is the root of the whole model - subproducts, pricing, forms, customizations, and webhooks are attached to a specific product. You create the product once.

Endpoints - Product

Method	Endpoint	Description
POST	`/api/product/pay`	Creates a product.
PATCH	`/api/product/pay/{productId}`	Updates a product.

Create product

POST /api/product/pay

{
  "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
  "productType": "PAY",
  "name": "Test Product",
  "shortName": "3456",
  "location": "Warsaw",
  "timezone": "Europe/Warsaw"
}

Field	Description
`partnerId`	Partner identifier (assigned by Paymove).
`productType`	Product type - for DocPay: `PAY`.
`name`	Product name.
`shortName`	Short display name.
`location`	Location (e.g. city).
`timezone`	IANA timezone (e.g. `Europe/Warsaw`).
`bankAccountDetails.iban`	Optional - IBAN of the payout account for this product’s payments (`PL` followed by 26 digits, no spaces). A subproduct can override it - example.
`bankAccountDetails.holderName`	Optional - account holder name.
`bankAccountDetails.nip`	Optional - account holder’s tax identification number (NIP).

Response (200):

{
  "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 is the product identifier (productId) used in the other endpoints.

Update product

PATCH /api/product/pay/{productId}

You can send only the fields to change; other relations (pricing, forms, webhooks) remain unchanged. This call does not change the payout account - you can only set it when the product is created.

Payout account (IBAN)

When creating the product you can set the account Paymove pays the funds from this product’s payments out to. Add a bankAccountDetails object to the body:

POST /api/product/pay

{
  "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
  "productType": "PAY",
  "name": "Test Product",
  "shortName": "3456",
  "location": "Warsaw",
  "timezone": "Europe/Warsaw",
  "bankAccountDetails": {
    "iban": "PL61109010140000071219812874",
    "holderName": "Partner Name Sp. z o.o.",
    "nip": "1234567890"
  }
}

The response then also contains bankAccountId - the identifier of the account stored on your partner account.

Only iban is required - in full: PL followed by 26 digits, upper case, no spaces. The checksum is verified and an invalid IBAN returns 400.

This is not the account the customer pays into. bankAccountDetails only decides where the paid-out funds go.

2. Subproduct and QR codes

A subproduct represents a single payment (e.g. payment request, ticket) linked to an external identifier (externalId). The response contains a QR code generated in the chosen format (PNG/SVG). After scanning, the user is taken to payment for that subproduct.

Input fields

Field	Description
`externalId`	Document identifier in your system. Displayed in the Paymove panel as the document number.
`imageFormat`	QR code image format: `svg` or `png`.
`bannerType`	Banner/card type (e.g. `ticket`) - affects presentation/layout.
`price`	Amount in minor units (e.g. `25000` = 250.00 PLN).
`details`	Key-value pairs displayed to the customer on the payment page (e.g. `"Document no.": "..."`).
`bankAccountDetails`	Optional - payout account for payments of this subproduct (`iban`, `holderName`, `nip`). Overrides the product’s account; ignored on a repeated `externalId`. Details: Subproduct payout account.

Endpoint - Subproduct

Method	Endpoint	Description
POST	`/api/pay/product/{productId}/subproduct`	Registers subproduct by `externalId` and generates QR code. After registration, the user can pay for the subproduct by scanning the code.

Register subproduct

POST /api/pay/product/{productId}/subproduct

{
  "externalId": "test-external#2",
  "imageFormat": "svg",
  "bannerType": "ticket",
  "price": 25000,
  "details": {
    "Document no.": "test-external#2"
  }
}

The response (200) is the binary image content with the QR code in the format set by imageFormat (Content-Type: application/octet-stream) - save the response body directly to a file. The image is a print-ready banner with a QR code redirecting to payment for this subproduct.

Subproduct payout account

A subproduct can have its own payout account - for example when payments for different documents should land in different accounts. The subproduct’s account overrides the product’s account; without it, the product’s account applies.

POST /api/pay/product/{productId}/subproduct

{
  "externalId": "test-external#3",
  "imageFormat": "svg",
  "bannerType": "ticket",
  "price": 25000,
  "details": {
    "Document no.": "test-external#3"
  },
  "bankAccountDetails": {
    "iban": "PL61109010140000071219812874",
    "holderName": "Partner Name Sp. z o.o.",
    "nip": "1234567890"
  }
}

The IBAN follows the same rules as for the product: full form without spaces, checksum verified, an invalid one returns 400 and no subproduct is created.
If an account with this IBAN already exists and you send a different holderName or nip, that account’s details are updated.
On a repeated externalId Paymove returns the existing subproduct and bankAccountDetails is ignored - you cannot change the account of a registered subproduct.

3. Pricing

Pricing defines payment options available to the customer - e.g. “1 hour”, “full day”, “weekend ticket”. Each entry is a separate purchase option shown on the product page.

Pricing entry fields

Field	Description
`price`	Amount in minor units (e.g. 150 = 1.50 PLN).
`description`	Human-readable description (e.g. “1 hour parking”).
`details`	Extra data for the entry - any key-value pairs, as a JSON object.

Endpoints - Pricing

Method	Endpoint	Description
GET	`/api/pay/products/{productId}/pricing/entries`	Returns all pricing entries for the product.
POST	`/api/pay/products/{productId}/pricing/entries`	Creates a new pricing entry.
PATCH	`/api/pay/products/{productId}/pricing/entries/{entryId}`	Updates a pricing entry.
DELETE	`/api/pay/products/{productId}/pricing/entries/{entryId}`	Deletes a pricing entry. Option no longer available at checkout.

Create pricing entry

POST /api/pay/products/{productId}/pricing/entries

{
  "price": 150,
  "description": "1 hour parking",
  "details": { "vat": 23, "unit": "hour" }
}

Update pricing entry

PATCH /api/pay/products/{productId}/pricing/entries/{entryId}

{
  "price": 150000000,
  "details": { "vat": 23, "unit": "hour" }
}

Changes are immediately visible to customers selecting that option.

4. Forms

Forms collect data required for purchase - e.g. email, license plate, contact details. Forms are versioned; each change (add/edit/remove field) creates a new version. The current version is marked with isCurrent.

Form field (Field) properties

Field	Description
`name`	Field name (e.g. `email`).
`type`	Type: `TEXT`, `NUMBER`, `SELECT`, `EMAIL`, etc.
`labels`	Language labels (e.g. `pl`, `en`).
`validators`	Validations: `required`, `pattern`, `maxLength`, etc.

Endpoints - Forms

Method	Endpoint	Description
GET	`/api/pay/product/{productId}/form`	List forms for PAY products.
GET	`/api/pay/product/{productId}/form/{formId}`	Form details (fields, version, isCurrent).
POST	`/api/pay/product/{productId}/form`	Creates a form for the product.
DELETE	`/api/pay/product/{productId}/form/{formId}`	Deletes a form. Does not affect data from completed purchases.

Endpoints - Fields

Method	Endpoint	Description
GET	`/api/pay/product/{productId}/form/field/{fieldId}`	Field details.
POST	`/api/pay/product/{productId}/form/{formId}/fields`	Adds a field - creates a new form version; new version becomes current.
PATCH	`/api/pay/product/{productId}/form/{formId}/field/{fieldId}`	Updates a field - creates a new form version with updated field.
DELETE	`/api/pay/product/{productId}/form/{formId}/field/{fieldId}`	Removes a field - creates a new version without that field.

Create form

POST /api/pay/product/{productId}/form

{
  "fields": [],
  "version": 1,
  "isCurrent": true
}

Add field (e.g. email)

POST /api/pay/product/{productId}/form/{formId}/fields

{
  "name": "email",
  "type": "TEXT",
  "labels": {
    "en": "Email",
    "pl": "Adres e-mail"
  },
  "validators": {
    "required": true,
    "maxLength": 100,
    "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
  }
}

This automatically creates a new form version; the previous one is no longer current (isCurrent).

5. UI customization

Customization controls the look and copy of the product checkout page. All text (titles, buttons, descriptions) is configured via API - the frontend is fully driven by the partner without code changes.

Customization parameters - what they modify

Parameter	What it modifies	Where it appears
`title`	Main page/product title.	Header at the top of the checkout view.
`subtitle`	Text below the title.	Directly under the title (subtitle).
`buttonText`	Call-to-action button label (e.g. “Buy now”, “Pay”).	Confirmation button on the payment page.
`summaryHeader`	Summary section heading.	Heading of the order summary block before payment.
`summaryFirstLine`	First line in the summary section.	Text in the summary (e.g. amount or product description).
`summarySecondLine`	Second line in the summary section.	Next line in the summary.
`cardDescription`	Product card description.	Description on the product card/listing (e.g. product picker or preview).
`locale`	Language/locale (e.g. `pl-PL`, `en-GB`).	Determines which text set is used; allows multiple customizations per product (e.g. PL and EN).

You can have multiple customizations per product with different locale; the system picks the right one by user or context.

Endpoints - Customization

Method	Endpoint	Description
GET	`/api/pay/product/{productId}/customization`	List all customizations.
GET	`/api/pay/product/{productId}/customization/{id}`	Customization details (all fields).
POST	`/api/pay/product/{productId}/customization`	Create customization for product.
PATCH	`/api/pay/product/{productId}/customization/{id}`	Update customization (any fields). Change is reflected immediately on the frontend.
DELETE	`/api/pay/product/{productId}/customization/{id}`	Delete customization. Product stops using that config; other customizations and services are unchanged.

Create customization

POST /api/pay/product/{productId}/customization

{
  "title": "New product",
  "subtitle": "Subtitle",
  "summaryHeader": "Summary header",
  "summaryFirstLine": "First line",
  "summarySecondLine": "Second line",
  "buttonText": "Buy now",
  "cardDescription": "Card description",
  "locale": "pl-PL"
}

Update customization

PATCH /api/pay/product/{productId}/customization/{id}

You can send only the fields you want to change, e.g.:

{
  "summaryFirstLine": "First line",
  "summarySecondLine": "Second line",
  "buttonText": "Buy now",
  "cardDescription": "Card description",
  "locale": "pl-PL"
}

Changes are immediately reflected on the product checkout page.

6. Webhooks

Webhooks automatically notify the partner of completed payments or fetch pricing from an external system. After registering a webhook, assign it to a product - then events for that product are sent to your endpoint.

Webhook configuration fields

Field	Description
`endpoint`	URL Paymove sends the request to (POST).
`method`	HTTP method (e.g. `POST`).
`headers`	Headers sent with the request (e.g. `Authorization`, `Content-Type`).
`requestTemplate`	Request body template (variables substituted by Paymove).
`responseTemplate`	Expected response structure from the partner.
`expectedCode`	Expected HTTP response code (e.g. 200).
`expectedResponse`	Expected response body (e.g. `{ "status": "ok" }`).
`retries`	Number of retries on failure.
`type`	Event type (e.g. `PAYMENT`).

Endpoints - Webhooks

Method	Endpoint	Description
GET	`/api/pay/plugin/webhook`	List webhooks. Optional query: `productId`.
GET	`/api/pay/plugin/webhook/{webhookId}`	Webhook details.
GET	`/api/pay/plugin/webhook/{webhookId}/products`	Products linked to the webhook.
POST	`/api/pay/plugin/webhook`	Create webhook.
POST	`/api/pay/plugin/webhook/{webhookId}/products/{productId}`	Assign webhook to product.
PATCH	`/api/pay/plugin/webhook/{webhookId}`	Update webhook. Affects all linked products.

Create webhook

POST /api/pay/plugin/webhook

{
  "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": "6909ca83-410f-47c4-910d-2057f8565a8c",
  "type": "PAYMENT",
  "headers": {
    "Authorization": ["Bearer abc123"],
    "Content-Type": ["application/json"]
  }
}

Response (200): the webhook object with an assigned id (webhook identifier) and a signingSecret field:

{
  "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"
}

The signingSecret is used to verify the signature of requests coming from Paymove. Store it securely.

After creating, call POST /api/pay/plugin/webhook/{webhookId}/products/{productId} to link the webhook to the product (response: the webhook object). From then on, events (e.g. successful payment) for that product are sent to your endpoint.

Introduction

Integrations

Tutorials

Help

Resources

1. Product

Endpoints - Product

Create product

Update product

Payout account (IBAN)

2. Subproduct and QR codes

Input fields

Endpoint - Subproduct

Register subproduct

Subproduct payout account

3. Pricing

Pricing entry fields

Endpoints - Pricing

Create pricing entry

Update pricing entry

4. Forms

Form field (Field) properties

Endpoints - Forms

Endpoints - Fields

Create form

Add field (e.g. email)

5. UI customization

Customization parameters - what they modify

Endpoints - Customization

Create customization

Update customization

6. Webhooks

Webhook configuration fields

Endpoints - Webhooks

Create webhook

​1. Product

​Endpoints - Product

​Create product

​Update product

​Payout account (IBAN)

​2. Subproduct and QR codes

​Input fields

​Endpoint - Subproduct

​Register subproduct

​Subproduct payout account

​3. Pricing

​Pricing entry fields

​Endpoints - Pricing

​Create pricing entry

​Update pricing entry

​4. Forms

​Form field (Field) properties

​Endpoints - Forms

​Endpoints - Fields

​Create form

​Add field (e.g. email)

​5. UI customization

​Customization parameters - what they modify

​Endpoints - Customization

​Create customization

​Update customization

​6. Webhooks

​Webhook configuration fields

​Endpoints - Webhooks

​Create webhook

1. Product

Endpoints - Product

Create product

Update product

Payout account (IBAN)

2. Subproduct and QR codes

Input fields

Endpoint - Subproduct

Register subproduct

Subproduct payout account

3. Pricing

Pricing entry fields

Endpoints - Pricing

Create pricing entry

Update pricing entry

4. Forms

Form field (Field) properties

Endpoints - Forms

Endpoints - Fields

Create form

Add field (e.g. email)

5. UI customization

Customization parameters - what they modify

Endpoints - Customization

Create customization

Update customization

6. Webhooks

Webhook configuration fields

Endpoints - Webhooks

Create webhook