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.

Working with an AI agent? It does steps 1-3 for you - all it needs is the API key and the partnerId; it asks for the shop name and the remaining fields itself. See Building with AI agents.

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",
  "metadata": {
    "locale": "pl-PL"
  }
}

Field	Type	Description
`partnerId`	`uuid`	Partner identifier (internal, assigned by Paymove)
`productType`	`enum`	Product type - `PAY` for payment gateway
`id`	`uuid`	Optional - your own product UUID. When omitted Paymove generates one; a UUID that already exists returns `400`
`name`	`string`	Shop name - the checkout shows it to the customer as the payee (a single payment can override it with `details.recipient`)
`fullName`	`string`	Optional - full company name. Included in the default webhook payload
`shortName`	`string`	Optional - short display name
`location`	`string`	Location - free text, e.g. a city or a country code. Not shown to the customer
`timezone`	`string`	IANA timezone (e.g. `Europe/Warsaw`)
`metadata.locale`	`string`	Optional - default checkout language (e.g. `pl-PL`)
`metadata.logoUrl`	`string`	Optional - public HTTPS URL of the shop logo. The checkout shows it next to the merchant name as a 34×34 px square (the image is cropped to a square); if it fails to load, a default icon is shown
`metadata.merchantDomain`	`string`	Optional - your shop’s domain (e.g. `shop.example.com`). Required only for Apple Pay in the modal checkout
`bankAccountDetails.iban`	`string`	Optional - IBAN of the payout account for this product’s payments (`PL` followed by 26 digits, no spaces). A single payment can override it - see Payout account. It can only be set when the product is created
`bankAccountDetails.holderName`	`string`	Optional - account holder name
`bankAccountDetails.nip`	`string`	Optional - account holder’s tax identification number (NIP)

2. Register a webhook

A webhook is a URL on your side that Paymove calls once a payment completes. 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`	Template of the payload sent to your endpoint. The field is required - it decides which data you receive. Variables are substituted as `{{name}}`, for example `{{externalId}}`, `{{price}}` or `{{status}}` - see Webhook payload for the full list
`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

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

Webhook payload

The payload shape depends on whether you set a requestTemplate. Without a requestTemplate Paymove sends the full payment object. Empty fields are omitted, so a given notification may carry fewer of them:

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

With a requestTemplate the payload is exactly what your template renders - nothing more, nothing less. For the template in step 2 you receive:

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

Every field of the default payload is available as a variable:

Variable	Description
`{{externalId}}`	Your order identifier - use it to match the payment
`{{orderId}}`	The order identifier on the Paymove side
`{{price}}`	Amount in grosze - the same one you sent when creating the payment
`{{status}}`	Payment status
`{{paymentMethod}}`	Payment method used
`{{email}}`	Customer email, if it was known
`{{date}}`	Payment creation time (Unix epoch)
`{{activeFrom}}`	Order creation time (Unix epoch)
`{{requestId}}`	Request identifier, useful in support tickets
`{{nip}}`	Tax identification number, if one was passed with the payment
`{{id}}`, `{{name}}`, `{{fullName}}`, `{{shortName}}`, `{{location}}`	Product data from its configuration

Values substituted into a text template arrive as strings - "price": "{{price}}" yields "1000", not 1000. A variable with no value renders as empty text.

The payload carries only the fields listed in your template. If you need to tell payment statuses apart, add {{status}} to it - otherwise your endpoint cannot distinguish notifications.

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