Easy webhooks

Use webhooks to be notified about events that happen to your payment.

Get transaction information with webhooks

Merchants has the possibility to subscribe to different events that affect a payment and to be notified directly when these events happen. When an event occurs in Easy; for example, a charge is made or a payment is refunded, this event can be sent along with the associated data directly to the merchant.


Configuring webhooks for a payment

Easy will send the event as a HTTP POST request to the URL specified by the merchant.

Webhooks are configured per payment and are specified in the create payment request.

When you subscribe to a webhook, Easy will try to send the request to the specified URL until the server responds with a 200 OK status code. If the server responds with anything else, or times out, a certain number of retries are made with increasing time between each attempt. Supported events for webhooks:

To register a webhook, use the following format:

		"webHooks": [{
			"eventName": "payment.refund.completed",
			"url": "https://www.example.com/callback/",
			"authorization" : "string"
		}]
	

The authorization field is used by Easy to set the authorization header of the http request when sending the webhook to the merchant site. This header should be verified by you to ensure that the request has come from the correct source.


Receive a webhook

It is very easy to receive a webhook. Just set up a new endpoint on the preferred site and read the JSON body of the request to get the event data.

C# code example:

		public async Task<ihttpactionresult> Post()
		{
			var content = await Request.Content.ReadAsStringAsync();
			dynamic eventData = JsonConvert.DeserializeObject(content);
			return Ok();
		}
	

Note that the webhooks need to be sent over HTTPS when designing the endpoint.


Webhook content

The webhook content will have the following format:

		{
			"id" : "f3d5043af4094d6887ee95bf16073958",
			"merchantId" : "e718004345cc48cba095a235de85c359",
			"timestamp" : "2018-01-12T09:40:19.8919+00:00",
			"event" : "payment.refund.completed",
			"data" : {
				...
				...
			}
		}
	

The data property inside will contain the event data for the specified event and will change accordingly.

See separate list for details on each event.


Responding to a webhook

To acknowledge the webhook sent from Easy, a 200 HTTP status code is required. Any other status code, even other 2XX codes, will be treated as a not successful attempt.

If the webhook was not successfully posted to you, Easy will continue to send the webhook with an increasing interval in time between each attempt. If your site still has not responded with 200 after this period, the webhook will not be attempted any more.


List of events and content

payment.created

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"order": {
					"amount": {
						"amount": ,
						"currency": ""
					},
					"reference": "",
					"orderItems": [{
							"grossTotalAmount": ,
							"name": "",
							"netTotalAmount": ,
							"quantity": ,
							"reference": " ",
							"taxRate": ,
							"taxTotalAmount": ,
							"unit": "",
							"unitNetPrice": 
						}, {
							"grossTotalAmount": ,
							"name": "",
							"netTotalAmount": ,
							"quantity": ,
							"reference": "",
							"taxRate": 2,
							"taxTotalAmount": ,
							"unit": "",
							"unitNetPrice": 
						}
					]
				},
				"paymentId": ""
			}
		}
	

pament.reservation.created

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"cardDetails": {
					"creditDebitIndicator": "",
					"expiryMonth": ,
					"expiryYear": ,
					"issuerCountry": "",
					"truncatedPan": ",
					"threeDSecure": {
						"acsUrl": "",
						"authenticationEnrollmentStatus": "",
						"authenticationStatus": "",
						"eci": ""
					}
				},
				"paymentMethod": "",
				"paymentType": "",
				"consumer": {
					"firstName": "",
					"lastName": "",
					"country": "",
					"email": "",
					"ip": "",
					"phoneNumber": {
						"prefix": "",
						"number": ""
					},
					"shippingAddress": {
						"addressLine1": "",
						"addressLine2": "",
						"city": "",
						"country": "",
						"postcode": ""
					}
				},
				"reservationReference": "",
				"reserveId": "",
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.charge.created

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"chargeId": "",
				"orderItems": [{
						"grossTotalAmount": ,
						"name": "",
						"netTotalAmount": ,
						"quantity": ,
						"reference": "",
						"taxRate": ,
						"taxTotalAmount": ,
						"unit": "",
						"unitNetPrice": 
					}
				],
				"reservationId": "",
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.charge.failed

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"error": {
					"code": "",
					"message": "",
					"source": ""
				},
				"chargeId": "",
				"orderItems": [{
						"grossTotalAmount": ,
						"name": "",
						"netTotalAmount": ,
						"quantity": ,
						"reference": "",
						"taxRate": ,
						"taxTotalAmount": ,
						"unit": "",
						"unitNetPrice": 
					}
				],
				"reservationId": "",
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.cancel.created

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"cancelId": "",
				"orderItems": [{
						"grossTotalAmount": ,
						"name": "",
						"netTotalAmount": ,
						"quantity": ,
						"reference": "",
						"taxRate": ,
						"taxTotalAmount": ,
						"unit": "",
						"unitNetPrice": 
					}
				],
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.cancel.failed

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"error": {
					"code": "",
					"message": "",
					"source": ""
				},
				"cancelId": "",
				"orderItems": [{
						"grossTotalAmount": ,
						"name": "",
						"netTotalAmount": ,
						"quantity": ,
						"reference": "",
						"taxRate": ,
						"taxTotalAmount": ,
						"unit": "",
						"unitNetPrice": 
					}
				],
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.refund.initiated

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"refundId": "",
				"chargeId": "",
				"orderItems": [{
						"grossTotalAmount": ,
						"name": "",
						"netTotalAmount": ,
						"quantity": ,
						"reference": "",
						"taxRate": ,
						"taxTotalAmount": ,
						"unit": "",
						"unitNetPrice": 
					}
				],
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.refund.completed

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"refundId": "",
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

payment.refund.failed

		{
			"id": "",
			"merchantId": "",
			"timestamp": "",
			"event": "",
			"data": {
				"error":{
					"code": "",
					"message": "",
					"source": ""
				},
				"refundId": "",
				"amount": {
					"amount": ,
					"currency": ""
				},
				"paymentId": ""
			}
		}
	

DATASTRING PARAMETERS

 

Supported events for webhooks

Event Description
payment.created When a payment is created.
payment.reservation.created When a customer successfully has reserved.
payment.charge.created When a payment has been charged. Partially or fully.
payment.charge.failed When a charge has failed.
payment.refund.initiated When a refund is initiated.
payment.refund.failed When a refund has not gone through.
payment.refund.completed When a refund has successfully been completed.
payment.cancel.created When a reservation has been canceled.
payment.cancel.failed When a cancellation did not go through.

 

Notifications

Parameter Type Description
webhooks webhook List of webhooks the merchant wants to register for the payment. Maximum number of webhooks is 32.

 

Webhooks

Parameter Type Description
event string The callback will be triggered for this payment event. See list for valid events.
url string The callback is sent to this url on the merchant site. Must be https. Maximum length is 256 characters.
authorization string Authorization header of the callback sent to the merchant site will be set to this value. Must be between 8 and 32 characters long and alphanumeric.

 

Do you have a question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00