Configuration

Integrating with the Paymove payment gateway consists of four steps: you create a product, register a webhook, assign it to the product, and then create payments via the SDK or REST API.

1. Create a product

A product represents your store in the Paymove system. All payments and subproducts are created within this product. Example product creation request:

POST https://gateway-api.sandbox.paymove.io/api/product/pay

{
  "partnerId": "{{partnerId}}",
  "productType": "PAY",
  "id": "2f6c19e8-84a7-4f50-b950-8d5a05e0bbf2",
  "name": "MerchantShop",
  "fullName": "Merchant Shop Sp. z o.o.",
  "shortName": "MShop",
  "location": "PL",
  "timezone": "Europe/Warsaw",
  "productMetadata": {
    "locale": "pl-PL"
  }
}

Field	Type	Description
`partnerId`	`uuid`	Partner identifier (internal, assigned by Paymove)
`productType`	`enum`	Product type - `PAY` for payment gateway
`id`	`uuid`	Product UUID
`name`	`string`	Short product name
`fullName`	`string`	Full company name
`shortName`	`string`	Display name
`location`	`string`	Location (country code)
`timezone`	`string`	IANA timezone (e.g. `Europe/Warsaw`)
`productMetadata.locale`	`string`	Optional - default checkout language (e.g. `pl-PL`)

2. Register a webhook

A webhook is a URL on your side that Paymove calls whenever a payment status changes. This way you don’t need to manually check the status - orders can be fulfilled automatically. For the list of possible statuses, see the status table. Example webhook registration request:

POST https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook

{
  "name": "PaymentSuccessHook",
  "endpoint": "https://merchant-shop.com/api/payments/webhook",
  "method": "POST",
  "requestTemplate": {
    "orderId": "{{externalId}}",
    "price": "{{price}}"
  },
  "responseTemplate": {
    "status": "ok"
  },
  "expectedCode": 200,
  "expectedResponse": "{ \"status\": \"ok\" }",
  "retries": 3,
  "partnerId": "{{partnerId}}",
  "type": "PAYMENT",
  "headers": {
    "Content-Type": ["application/json"]
  }
}

Field	Type	Description
`name`	`string`	Webhook name
`endpoint`	`string`	URL where Paymove sends a notification after a successful payment
`method`	`enum`	HTTP method (`POST`)
`requestTemplate`	`object`	Payload template - every field of the default payload is available as a variable, including `{{externalId}}`, `{{price}}`, `{{status}}` and `{{paymentMethod}}`
`responseTemplate`	`object`	Expected response structure from the merchant
`expectedCode`	`integer`	Expected HTTP response code (`200`). The field is required - omitting it results in a `500` error
`expectedResponse`	`string`	Expected response as a JSON string. Stored on the webhook but never compared against the actual response
`retries`	`integer`	Number of retry attempts on failure. The field is required - omitting it results in a `500` error. A value of `0` means no retries
`partnerId`	`uuid`	Partner identifier (internal)
`type`	`enum`	Event type (`PAYMENT`)
`headers`	`object`	HTTP headers attached to the webhook

How the webhook works

By default the webhook is sent only for the COMPLETED status. Notifications for the remaining statuses (CANCELED, ERROR, REFUNDED) must be enabled by Paymove for your specific product - write to integration@paymove.io.

Payment statuses in Paymove:

Status	Meaning
`INITIALIZED`	Payment created, the customer has not paid yet
`PENDING`	Payment in progress on the provider’s side
`COMPLETED`	Payment succeeded - fulfil the order
`CANCELED`	The customer cancelled the payment
`ERROR`	The payment failed
`REFUNDED`	The payment was refunded
`WAITING_FOR_EXTERNAL_ACTION`	Transient internal Paymove state - not a terminal state

The status is always sent as a string (e.g. "COMPLETED"). The numbers found in older integrations are an internal database representation and never appear in the API or in webhooks.

Webhook payload

The payload shape depends on whether you set a requestTemplate. Without a requestTemplate Paymove sends the full object (empty fields are omitted):

{
  "id": "891412c8-8717-4449-9543-e34112bec470",
  "name": "MerchantShop",
  "fullName": "Merchant Shop Sp. z o.o.",
  "shortName": "MShop",
  "location": "PL",
  "externalId": "order-123",
  "orderId": "PAY1784798914400",
  "price": 950,
  "status": "COMPLETED",
  "paymentMethod": "BLIK",
  "email": "customer@example.com",
  "date": 1783246791.745352526,
  "requestId": "8f2b1c44-0d7e-4a91-b2c3-5e7f9a1d3c60"
}

In the default payload, price is the amount minus the Paymove fee, not the amount charged to the customer. If you verify the amount, compare it against the value you stored when creating the payment, not against this field.

With a requestTemplate the payload is exactly what your template renders. For the template from step 2:

{
  "orderId": "order-123",
  "price": "1000"
}

Field	Type	Description
`orderId`	`string`	The `{{externalId}}` value - your order identifier
`price`	`string`	The `{{price}}` value - amount in grosze (as a string)

Signature verification

Every webhook request carries an X-Paymove-Signature header. Verify it before trusting the payload - without verification, anyone who knows your URL can impersonate Paymove and have an order fulfilled without paying. Ready-to-copy code for Node.js, Python and Java: Webhook signature verification.

Required response

Your server must respond with an HTTP status equal to expectedCode. The customary body to return alongside it is:

{ "status": "ok" }

Delivery success is decided by the HTTP status alone, and it must be exactly equal to expectedCode. With the default 200, a 201 or 204 response counts as a failure - and worse, it is not retried: only 4xx, 5xx and network errors trigger the retry schedule. A wrong 2xx loses the notification for good.

The response body is never inspected. expectedResponse is stored on the webhook and echoed back by the API, but it is never compared against what your server returns - any body will do.

If delivery fails, the webhook is retried as many times as retries specifies - 0 by default, meaning not at all. With retries set, the next attempts follow after 1 s, 5 s, 5 min, 1 h, and then every 3 h.

Paymove applies no timeout to webhook calls. Respond immediately and do the actual order processing asynchronously - otherwise a slow endpoint blocks processing.

3. Assign webhook to product

After creating a product and registering a webhook, you need to link them together. This way every payment event related to this product is automatically sent to the specified webhook URL. Example request:

POST https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/{webhookId}/products/{productId}

Parameter	Type	Description
`webhookId`	`uuid`	Webhook identifier received in point 2
`productId`	`uuid`	Product UUID created in point 1

4. Creating payments

After configuring the product and webhook, you can start creating payments. Choose your integration method:

SDK

Node.js package - initialize the client and call createPayment.

REST API

Direct HTTP calls - works with any language.

Introduction

Integrations

Tutorials

Help

Resources

1. Create a product

2. Register a webhook

How the webhook works

Webhook payload

Signature verification

Required response

3. Assign webhook to product

4. Creating payments

SDK

REST API

​1. Create a product

​2. Register a webhook

​How the webhook works

​Webhook payload

​Signature verification

​Required response

​3. Assign webhook to product

​4. Creating payments

SDK

REST API

1. Create a product

2. Register a webhook

How the webhook works

Webhook payload

Signature verification

Required response

3. Assign webhook to product

4. Creating payments