Payment statuses

Statuses

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

WAITING_FOR_EXTERNAL_ACTION is a transient state, set briefly while Paymove finishes processing. It is not terminal and does not mean the payment needs customer action. You may observe it by polling at an unlucky moment - treat it like PENDING.

Note the spelling CANCELED - with a single “l”.

Webhook payload

The shape depends on whether you set a requestTemplate when registering the webhook.

Without a `requestTemplate`

Paymove sends the full payment object. Empty fields are omitted, so a given notification may contain fewer of them:

{
  "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": 1000,
  "status": "COMPLETED",
  "paymentMethod": "BLIK",
  "email": "customer@example.com",
  "date": 1783246791.745352526,
  "activeFrom": 1783246791.740112000,
  "requestId": "8f2b1c44-0d7e-4a91-b2c3-5e7f9a1d3c60"
}

Field	Description
`id`	The UUID of your product (store), not of the payment
`name`, `fullName`, `shortName`, `location`	Product data from the configuration
`externalId`	Your order identifier - use it to match the payment
`orderId`	Paymove’s internal order identifier
`price`	Amount in grosze - the same one you sent when creating the payment
`status`	Payment status
`paymentMethod`	The payment method used
`email`	The customer’s email, when known
`date`	Payment creation time (Unix epoch)
`activeFrom`	Order creation time (Unix epoch)
`requestId`	Request identifier, useful when contacting support

price matches the amount you sent when creating the payment, so you can compare it against the value you stored. The customer sees that amount plus the fee on the checkout, if your product charges one.

The payload contains no event or type field and is not wrapped in an envelope. It is a flat object, and you identify the kind of event from the status field.

With a `requestTemplate`

The payload is exactly what your template renders. For the template {"orderId": "{{externalId}}", "price": "{{price}}"} you receive:

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

A template can use every field of the default payload - including {{status}}, {{paymentMethod}}, {{email}}, {{date}} and {{orderId}}, not just {{externalId}} and {{price}}. Note that values substituted into a text template arrive in the payload as strings.

A template gives you control over the payload shape and contains exactly what you write into it. If you need to distinguish statuses, add {{status}} to the template or leave requestTemplate unset altogether.

Querying the status

Useful as a supplement to the webhook - for example when the customer is back on returnUrl but the notification has not arrived yet.

This endpoint lives under a different base URL from the rest of the API. It is not routed through gateway-api.sandbox.paymove.io or api.paymove.io - calling it there returns 404 with a text/plain body reading No route found for: GET …, which is not even the standard {status, message} shape.

Environment	Base URL for the status query
Sandbox	`https://pay-api.sandbox.paymove.io`
Production	`https://pay-api.paymove.io`

curl "https://pay-api.sandbox.paymove.io/api/payment/product/{productId}/subproduct/{paymentHash}/status"

{
  "status": "COMPLETED",
  "orderId": "PAY1784798914400"
}

Parameter	Description
`productId`	The UUID of your product, or its `shortName`
`paymentHash`	The 10-character payment hash from the `externalId` parameter in `redirectUrl`

If no payment exists for the given hash you receive:

{
  "status": 404,
  "message": "Payments for externalId ec6RtwTZKb not found"
}

paymentHash is not the externalId you passed when creating the payment. It is a value generated by Paymove and returned inside redirectUrl - for example ec6RtwTZKb in https://checkout.sandbox.paymove.io/{productId}?externalId=ec6RtwTZKb. Store it when you create the payment.

This endpoint requires no API key. Do not pass sensitive data to it, and do not treat its response alone as the only proof of payment in critical flows - the trustworthy confirmation is a verified webhook.

Recommended flow

Create the payment and store your externalId together with the payment hash from redirectUrl.
Redirect the customer to the checkout.
On the returnUrl page show a “we are processing your payment” message - no fulfilment.
Wait for the webhook, verify its signature and fulfil the order idempotently.
If the webhook has not arrived by the time the customer returns, query the status so you can show the right message immediately.

Refunds

Refunds are handled by Paymove - there is no public API endpoint for issuing them. If you need to refund a payment, contact integration@paymove.io. Once refunded, the payment takes the REFUNDED status.

Introduction

Integrations

Tutorials

Help

Resources

Statuses

Webhook payload

Without a `requestTemplate`

With a `requestTemplate`

Querying the status

Recommended flow

Refunds

What’s next

Signature verification

Webhook configuration

​Statuses

​Webhook payload

​Without a requestTemplate

​With a requestTemplate

​Querying the status

​Recommended flow

​Refunds

​What’s next

Signature verification

Webhook configuration

Statuses

Webhook payload

Without a `requestTemplate`

With a `requestTemplate`

Querying the status

Recommended flow

Refunds

What’s next