> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment webhooks

> Receiving provider notifications and verifying signatures.

Providers confirm a payment by sending a notification to a public webhook endpoint. After signature verification, the API updates the order status.

## Endpoint

```http theme={null}
POST /api/v2/payments/webhooks/{provider}/{shopId}/{webhookSecret}
```

* `provider` — provider name (e.g. `imojeTransfer`, `zen`, `paymentic`)
* `shopId` — the shop the method belongs to
* `webhookSecret` — the payment method's secret (set during configuration)

Configure the webhook URL on the provider's side, or it is passed automatically when the session is created.

## Signature verification

Each provider signs the notification with its own secret and passes the signature in a header. ItemShop verifies that signature against the original, unmodified request body before processing it. The signing scheme is documented by each provider:

| Provider  | Signature header                          |
| --------- | ----------------------------------------- |
| imoje     | `X-Imoje-Signature`                       |
| ZEN       | IPN hash carried in the notification body |
| Paymentic | `X-Paymentic-Signature`                   |
| Stripe    | `Stripe-Signature`                        |

<Warning>
  A webhook with an invalid signature is rejected. Verification runs on the original body, so do not modify the notification at a proxy layer.
</Warning>

## Status mapping

The provider sends a transaction status that the API maps to an order status:

| Provider status (examples)                   | Order status                         |
| -------------------------------------------- | ------------------------------------ |
| `settled`, `ACCEPTED`, `PAID`                | `paid` (paid, ready for fulfillment) |
| `cancelled`, `rejected`, `FAILED`, `EXPIRED` | `cancelled`                          |
| `pending`, `CREATED`                         | no action                            |

After moving to `paid`, ItemShop automatically sends the confirmation email and the Discord notification.

## Response

After successful processing, the endpoint returns `200` with `{ "received": true }`. Providers treat a `2xx` code as confirmation of receipt.