"text":"Simulate payments to test your integration before launching in production.",
"title":"Create your payment form",
"text":"Understand how to integrate the payment form into your product.",
"text":"Explore diverse payment options for a seamless experience.",
Subscribe for events on your Solidgate account so your integration can automatically trigger actions
In Solidgate, asynchronous events for payments, subscriptions, and chargebacks are facilitated through webhooks, ensuring our clients receive all the necessary information. A webhook consists of a URL provided by the external application, and the payment system sends an HTTP request to that URL when a subscribed event occurs. Solidgate then sends a POST request to the merchant’s endpoint, containing event details in the request body.
The merchant's server subsequently processes the incoming request, utilizing its predefined business logic to handle the information.
Here is an overview on how webhooks work in Solidgate:
The merchant establishes an endpoint on their server for Solidgate to send webhook notifications.
To enable this process, the merchant registers their webhook handler in the
system. During registration, they are required to provide the handler URL and select the specific event types they wish to subscribe to.
Upon the occurrence of a subscribed event, Solidgate dispatches an HTTP POST request containing event details to the merchant's endpoint.
The merchant's server obtains and processes the request based on their established business logic.
The merchant's server returns an HTTP response to Solidgate, confirming the webhook receipt and processing.
It is important to note that the merchant should ensure that the endpoint is always available and can handle incoming requests promptly to avoid missing any important notifications.
You can manage webhooks within the
by navigating to the channel settings located in the developer section.
It is feasible to configure up to 20 distinct endpoints for receiving the following event types:
Updated Card Order Reflects a change in the status of a card order.
Updated Alternative Order Represents an update on the status of an alternative order.
Updated Subscription Highlights a modification in the subscription or related order status.
Network Token Created Indicates that a network token is issued either by Visa Token Service or Mastercard Digital Enablement Service.
Network Token Updated Reflects a change in the status of a network token.
Received Card Chargeback Indicates the receipt of a new dispute for the card order.
Received Card Prevent Alert Signifies the reception of an Issuer Network alert.
Received Card Fraud Alert Denotes the acquisition of a TC40/SAFE alert.
If you opt to receive identical events across multiple endpoints, webhook notifications are dispatched to all specified endpoints.
Upon receipt of webhook notifications, your server must acknowledge and issue a 2xx HTTP status code response within 30 seconds. Failure to respond results in a webhook failure, prompting subsequent resending attempts.
Below is a list of events you can receive to automate your system, each accompanied by a unique signature for identifying Solidgate transactions in accordance with the API access rules.
Card order status
Webhook Allows merchants to securely receive real-time card order status updates (e.g., processing or declined) and automatically initiate relevant actions or system changes.
Network token created
Webhook Allows merchants to receive real-time notifications that the network token associated with a payment card is issued by Visa or Mastercard, enabling them to automatically update their systems based on these events.
Network token updated
Webhook Allows merchants to receive real-time notifications when the network token associated with a payment card is updated by Visa or Mastercard, enabling them to automatically update their systems in response.
Webhook Enables secure real-time chargeback event notifications for merchants, allowing automated system actions or updates based on these events.
Webhook Offers secure, real-time chargeback notifications for merchants, enabling prompt dispute resolution and loss minimization.
Webhook Enables secure, real-time fraud alerts for merchants, facilitating swift action to prevent losses.
If the webhook notification fails due to an incorrect response, the retry mechanism automatically makes several attempts to resend it.
Notification delivery attempts follow the structured schedule below:
15 minutes after the initial failed notification
30 minutes after the first failed retry
1 hour after the second failed retry
2 hours after the third failed retry
4 hours after the fourth failed retry
8 hours after the fifth failed retry
16 hours after the sixth failed retry
24 hours after the seventh failed retry
Webhook event security is handled similarly to API authentication. In each notification, you receive the
Learn to authenticate API requests and generate signatures.
Learn to authenticate API requests and generate signatures.
values in the headers.
The merchant value corresponds to the webhook
Learn to authenticate API requests and retrieve your credentials.
The signature value is calculated using the webhook public and secret keys, which helps verify the authenticity and integrity of the webhook data transmitted between Solidgate and the merchant’s server.
The data variable within the generateSignature function pertains to the payload transmitted via the webhook. This data can include event-related information, like order events, and is sent by Solidgate as part of the triggering HTTP request body.
You need to retrieve the merchant wh_pk_ from the request headers and verify if you possess the corresponding credentials.
Generate a signature from the received body using the generateSignature function, as you would when sending a request to a gateway.
Occasionally, you may receive duplicate events during notification retries or when resending requested events. To mitigate this, consider implementing idempotent processing in your integration.
This approach helps prevent the negative effects of duplicate events.
Each action’s unique event ID, provided in the request header parameters, is crucial for monitoring and managing webhook events.
Unique event ID: a crucial identifier for monitoring and managing webhook events.
Handling non-ordered events
In Solidgate, webhooks are essential for asynchronous event communication, such as payments, subscriptions, and chargebacks. It’s important to understand that the order of received webhook events may not always match the sequence of their occurrence. This section offers guidance on effectively managing non-ordered events.
The delivery order of webhooks is not guaranteed. Relying solely on the sequence of event occurrence when processing webhooks could lead to inaccuracies in event handling.
Managing non-ordered events
Accumulating webhooks: Temporarily store incoming webhooks (e.g., for about a minute) before processing. This delay allows for the collection of all relevant webhooks, aiding in more accurate event processing.
Handling event collisions: In cases where an event cannot be processed due to insufficient data, often resulting from delayed delivery of some events, utilize the
to retrieve the necessary information.
Asynchronous event processing: Implement a queue-based approach for processing incoming events, rather than handling them synchronously. This is crucial due to the timeout constraints on webhook sending. Synchronous processing that exceeds the timeout limit may lead to webhooks being marked as undelivered, which can complicate the order of event processing.
Adopting these best practices enables merchants to effectively manage non-ordered events in webhooks, ensuring accurate and reliable event processing in their systems.