Webhook Event

The Payment Processing Completed Webhook is sent by Convergegate to notify your system when a payment has reached a finalized state. This webhook enables real-time updates in your application without polling the API.

---

🔒 Authorization

• Type: SignatureAuth

• Signature Algorithm: HMAC-SHA256

• Secret: Shop Signing Key

• Header Parameter Name: Signature

• The signature is computed from the raw JSON request body using the Shop Signing Key as the HMAC secret.

⚠️ Important: The Signature header is only included after a Signing Key has been generated for the shop. Without a Signing Key, webhook requests will not include this header. You can generate a Signing Key in the merchant back office.

---

Webhook URL

The webhook endpoint must be implemented by the merchant and exposed via HTTPS. Your server should respond with HTTP 200 OK to confirm successful receipt. Any non-2xx response will trigger retries according to Convergegate retry policy.

---

Payload Structure

Content-Type: application/json

Field	Type	Description
id	string (≤ 32 chars)	Payment ID.
referenceId	string (≤ 256 chars)	Merchant-provided reference ID.
created	string (ISO 8601)	Payment creation date/time (UTC).
paymentType	string	One of: DEPOSIT, WITHDRAWAL, REFUND.
state	string	Final state: COMPLETED, DECLINED, CANCELLED.
description	string (≤ 512 chars)	Transaction description.
parentPaymentId	string (≤ 32 chars)	ID of the initial payment in the chain.
paymentMethod	string	One of: BASIC_CARD, BASIC_CARD_HPP, PIX, OPEN_BANKING, BLIK.
paymentMethodDetails	object	Amount, currency, and provider-specific info.
errorCode / errorMessage	string	Populated for failed payments.
customer	object	Customer and billing details.
redirectUrl	string	Redirect URL for the customer (if applicable).

Example Webhook Body

{
  "id": "a1b2c3d4e5f6g7h8i9j0",
  "referenceId": "ORDER-12345",
  "created": "2025-08-14T15:32:00Z",
  "paymentType": "DEPOSIT",
  "state": "COMPLETED",
  "description": "Payment for ORDER-12345",
  "parentPaymentId": "z9y8x7w6v5u4t3s2r1q0",
  "paymentMethod": "BLIK",
  "paymentMethodDetails": {
    "amount": 100.00,
    "currency": "PLN"
  },
  "customer": {
    "billingAddress": {
      "line1": "Main Street 123",
      "city": "Warsaw",
      "country": "PL",
      "zip": "00-410"
    }
  }
}

Verifying the Signature

1. Retrieve the Signature header from the webhook request.

2. Compute HMAC-SHA256 over the raw JSON body using the Shop Signing Key.

3. Compare the result to the value in the Signature header.

4. Reject the request if the values do not match.

---

Best Practices

• Always validate the signature before processing the webhook.

• Store and log the raw webhook payload for troubleshooting.

• Use idempotency in your processing logic to avoid double updates.

• Make sure your webhook endpoint is publicly accessible and HTTPS-secured.