Webhooks – Asynchronous events
Webhooks are used to notify about events that happen during the lifetime of installment plan.
• An event is an occurrence, such as installment plan approval, a monthly charge or a refund.
• Endpoints are URLs defined by users to which splitit sends events. A single event may be sent to single endpoint.
• Webhooks refers to the overall concept of sending notifications to webhook endpoints.
Webhooks can help with the following use cases:
- Hosted solution – when merchant checkout is directed to splitit form to fulfill the payment process and for some reason the redirection back to merchant checkout failed due to communication issues from your shopper browser or temporary problem on merchant server, the order may not be closed although plan was created successfully on splitit.
- Online administration activities – when administration activities are done both on splitit and merchant portals, merchant portal may need to be updated whenever action is done on splitit side.
- Scheduled activities – Merchant’s systems may need to be notified on Scheduled processes as monthly charges, authorizations etc.
Webhooks can handle above use cases by letting you register a URL that we will notify anytime an event happens in your account. When the event occurs splitit will send a message containing the event type and standard data that represent the state of the plan on the time the event occur. Splitit will than send this data to the defined URLs in your account via an HTTP POST request,
The event with the data will be sent to the endpoint you define periodically every 1 hour for 24 hours until your server will response with HTTP code 200 so if your server is down temporary, once the server will recover, your server will get the data.
Remark: you only need to use webhooks for behind-the-scenes transactions. The results of most requests (example: Initiate, Cancel, Refund) are reported synchronously and don’t require webhooks.
|Scheduled Monthly charge completed Successfully\Failed|
|Partial\Full refund Succeeded\Failed|
|Full installment plan capture Succeeded\Failed|
|Plan Creation (and authorized) Succeeded\Failed|
|Plan Approval (by shopper) Succeeded\Failed|
|Plan cancellation Succeeded\Failed|
|Initiate of first installment Succeeded\Failed|
|PlanCleared||Plan outstanding amount = 0|
|PlanDelayed||When plan entering delay for any reason|
|PlanRecovered||When plan recovered after delay|
Currently there is no UI for webhooks configuration (planned for future release) in order to configure webhook, please contact your account manager by mail with the following details:
1. The event (from above list) you would like to be registered to.
2. The endpoint URL that should be configured for this webhook
Webhooks implementation on merchant server
In order to implement webhooks on merchant side, merchant will need to expose URL that will response with http status code 200 after analyzing the webhook data.
Webhook data is sent as JSON in the POST request body. The data contains the following:
- The Event type
- The full plan data on the time of the event.
Following is schematic representation of the json data sent in the post message:
Example of the Json data can be found here
Full documentation of Installment plan element data in the Json body can be found here