Skip to main content
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"
  }
}
FieldDescription
partnerIdPartner identifier (internal, assigned by Paymove)
productTypeProduct type - PAY for payment gateway
idProduct UUID
nameShort product name
fullNameFull company name
shortNameDisplay name
locationLocation (country code)
timezoneIANA timezone (e.g. Europe/Warsaw)
productMetadata.localeOptional - 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"]
  }
}
FieldDescription
nameWebhook name
endpointURL where Paymove sends a notification after a successful payment
methodHTTP method (POST)
requestTemplatePayload template - variables {{externalId}} and {{price}} are dynamically substituted
responseTemplateExpected response structure from the merchant
expectedCodeExpected HTTP response code (200)
expectedResponseExpected response as a JSON string
retriesNumber of retry attempts on failure
partnerIdPartner identifier (internal)
typeEvent type (PAYMENT)
headersHTTP headers attached to the webhook

​
How the webhook works

Paymove notifies the webhook about payment status changes. Notifications are sent for the following statuses:
StatusCode
INITIALIZED-2
CANCELED-1
PENDING0
COMPLETED1
ERRORerror
REFUNDED2
WAITING_FOR_EXTERNAL_ACTION3
Whether a given status is handled depends on the partner - configuration is set individually in the partner’s system. When a payment succeeds, Paymove sends a POST to your URL with the following payload: 
{
  "orderId": "order-123",
  "price": "1000"
}
FieldDescription
orderIdYour order identifier (externalId from the payment creation request)
priceAmount in minor units (as a string)

​
Required response

Your server must respond with: 
{ "status": "ok" }
If a valid response (HTTP 200 with the expected body) is not received, the webhook will be retried - the default configuration is 3 retry attempts.

​
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/{merchantId}
ParameterDescription
webhookIdWebhook identifier received in point 2
merchantIdProduct 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.