Payment Gateway: webhooks

A webhook is how Paymove actively notifies your system about a completed payment - no API polling required. The setup takes two steps: you register a webhook, then assign it to a product (your store). From that moment on, every paid transaction in that store is delivered to the endpoint you specified. 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. You need your partnerId and the productId of the store created in the Payment Gateway: basic integration tutorial.

Step 1: Register a webhook

In requestTemplate you define the request body Paymove will send to your endpoint. You can use the variables {{externalId}} (your order identifier) and {{price}} (the amount) - Paymove substitutes them when sending.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "name": "OrderPaymentHook",
    "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": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "type": "PAYMENT",
    "headers": {
      "Authorization": ["Bearer abc123"],
      "Content-Type": ["application/json"]
    }
  }'

Field	Description
`name`	Webhook name (visible in the configuration).
`endpoint`	URL Paymove sends the request to.
`method`	HTTP method (e.g. `POST`).
`requestTemplate`	Request body template (variables substituted by Paymove).
`responseTemplate`	Expected response structure from the partner.
`expectedCode`	Expected HTTP response code (e.g. 200).
`expectedResponse`	Expected response body (e.g. `{ "status": "ok" }`).
`retries`	Number of retries on failure. Defaults to `0` - set it explicitly if you want retries.
`partnerId`	Partner identifier (assigned by Paymove).
`type`	Event type - for payment notifications: `PAYMENT`.
`headers`	Headers attached to the request (e.g. `Authorization`, `Content-Type`).

Response (200):

{
  "id": "6b23ecd9-14c8-47fc-add0-b71ec50e9d66",
  "name": "OrderPaymentHook",
  "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,
  "type": "PAYMENT",
  "headers": {
    "Authorization": ["Bearer abc123"],
    "Content-Type": ["application/json"]
  },
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

The id field in the response is the webhook identifier (webhookId) you will use in step 2.

The response contains a signingSecret - a secret for verifying the signature of requests coming from Paymove. Store it securely on your side and never expose it publicly.

Step 2: Assign the webhook to your store

The webhook only starts working once it is linked to a product. In the URL, replace webhookId (from step 1) and the productId of your store.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/products/891412c8-8717-4449-9543-e34112bec470 \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response (200): the webhook object (same as in step 1), confirming the link. From now on, every completed payment in this store triggers your endpoint.

Verify the configuration

You can list the products linked to a webhook with:

curl --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/products \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response (200): an array of products linked to the webhook:

[
  {
    "id": "891412c8-8717-4449-9543-e34112bec470",
    "name": "Sklep Testowy",
    "productType": "PAY",
    "status": "ACTIVE"
  }
]

What does a payment notification look like?

After a completed payment, Paymove sends a request to your endpoint matching the requestTemplate and configured headers. For the template from step 1, the body looks like this:

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

orderId is the externalId you passed when creating the payment - it lets you unambiguously match the notification to an order in your system.

The shape above is the result of the requestTemplate. With an empty template, Paymove sends the full payment object instead - the field set is described in Configuration.

Before trusting the notification, verify the X-Paymove-Signature header. Without it, anyone who knows your endpoint can send a forged notification and have an order fulfilled without paying. Ready-to-copy code: Webhook signature verification.

Your system should respond with a status exactly equal to expectedCode (customarily 200 with a { "status": "ok" } body, though the body is never inspected) - only then does Paymove consider the delivery successful. A 201 or 204 response against expectedCode: 200 counts as a failure and is not retried. Deliveries that end in a 4xx, a 5xx or a network error are retried as many times as retries specifies - 0 by default, meaning not at all.

Fulfil the order when you receive the webhook, not when the customer returns to your returnUrl - the customer may close the browser before coming back to your store, and the redirect itself can be triggered without paying.

Introduction

Integrations

Tutorials

Help

Resources

Step 1: Register a webhook

Step 2: Assign the webhook to your store

Verify the configuration

What does a payment notification look like?

What’s next?

Payment Gateway: basic integration

Webhooks

​Step 1: Register a webhook

​Step 2: Assign the webhook to your store

​Verify the configuration

​What does a payment notification look like?

​What’s next?

Payment Gateway: basic integration

Webhooks

Step 1: Register a webhook

Step 2: Assign the webhook to your store

Verify the configuration

What does a payment notification look like?

What’s next?