DocPay: basic integration

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.

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

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

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

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?

REST API

Full endpoint reference: pricing, forms, UI customization and webhooks (payment notifications).

Introduction

Integrations

Tutorials

Help

Resources

Step 1: Create product

Step 2: Create subproduct

Response: QR code

What’s next?

REST API

​Step 1: Create product

​Step 2: Create subproduct

​Response: QR code

​What’s next?

REST API

Step 1: Create product

Step 2: Create subproduct

Response: QR code

What’s next?