Skip to content

Attention merchants! How to choose a ‘BNPL’ solution in 5 simple steps. Learn more

Webhooks

Webhooks – Asynchronous events

Webhooks are used to notify about events that happen during the lifetime of installment plan.

Terminology:

  • 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.

Events Description
ChargeSucceeded

ChargeFailed
Scheduled Monthly charge completed

Successfully\Failed
RefundSucceeded

RefundFailed
Partial\Full refund Succeeded

Failed
FullCaptureSucceeded

FullCaptureFailed
Full installment plan capture Succeeded

Failed
PlanCreatedSucceeded

PlanCreatedFailed
Plan Creation (and authorized) Succeeded

Failed
PlanApprovedSucceeded

PlanApprovedFailed
Plan Approval (by shopper) Succeeded

Failed
PlanCancelledSucceeded

PlanCancelledFailed
Plan cancellation Succeeded

Failed
StartInstallmentsSucceeded

StartInstallmentsFailed
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

Increase Conversion by Offering Monthly Payments

Get personalized tips on how to grow sales, lower cart abandonment and the latest payment trends.