Integration

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.

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):

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

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.:

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?

DocPay: webhooks

Add a webhook and receive automatic notifications about every completed payment.

REST API

Full PAY API endpoint reference: pricing, forms, UI customization and webhooks.

Introduction

Integrations

Tutorials

Help

Resources

Step 1: Create a product

Step 2: Create a subproduct (payment link)

Response: QR code with the payment link

What’s next?

DocPay: webhooks

REST API

​Step 1: Create a product

​Step 2: Create a subproduct (payment link)

​Response: QR code with the payment link

​What’s next?

DocPay: webhooks

REST API

Step 1: Create a product

Step 2: Create a subproduct (payment link)

Response: QR code with the payment link

What’s next?