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

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

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

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.