Webhooks

MobilePay uses webhooks to notify your application when an event happens in your account. They are useful for asynchronous events, e.g. when a customer confirms a payment. When an event occurs, MobilePay collects data about the event, creates an event notification and sends the event notification to the notification URL for all webhook subscriptions that are subscribed to the event.

When to use webhooks

Many events that occur within a MobilePay merchant account have synchronous results immediately. E.g., a successful payment initiation will return Payment object. Such requests don't require webhooks as the key information is already available.

Other events that occur are asynchronous: happening at a later time and not directly in response to your code's execution. With those APIs, MobilePay needs to notify your integration about changes to the state of an object so your integration can take subsequent steps.

The specific actions your webhook endpoint may take differs based upon the event. I.e.:

• Capturing a payment when payment state has changed (user has approved it).
• Updating records in your systems when payment point is activated and ready to be used.

Best practices for using webhooks

Review these best practices to ensure your webhooks remain secure and function seamlessly with your integration.

Event types

You should subscribe to the types of events required by your integration. Listening for extra events will put extra strain on your/our infrastructure and is not recommended.

You can change the events by updating your webhooks configuration.

Requirements and limitations

• Your notification URL must return 2xx HTTP status code within 10s. Otherwise the notification will be retried with exponential backoff.
• Notification attempt schedule:

Attempt number	Time since last attempt	Time since initial notification*
1	-	-
2	30 seconds	30 seconds
3	1 minute	1.5 minutes
4	2 minutes	3.5 minutes
5	4 minutes	7.5 minutes
6	8 minutes	15.5 minutes
7	16 minutes	31.5 minutes
8	32 minutes	63.5 minutes
9	64 minutes	2 hours
10 - 32	120 minutes	4 - 48 hours

* Approximate values since retries are scheduled after delivery attempt which might take up to 10 seconds.

danger

• After all retries have been exhausted the notification is never sent again.
• There is no guarantee of the delivery order.

Check the webhook signatures

All webhook notifications from MobilePay include a x-mobilepay-signature header. The value of this header is a HMAC-SHA1 signature generated by concatenating your webhook's notification URL with the body of the request (excluding all whitespaces) and hashing it using the signature key. You can validate the webhook notification by generating the HMAC-SHA1 in your code and comparing it to the signature of the event notification you received. The hash is sent in standard base64 format RFC 4648 §4 (do not mistake with base64url format RFC 4648 §5).

Example pseudocode that generates signature:

var signature = new HMACSHA1(signatureKey)
  .computeHash(notificationUrl + notificationBody.removeWhitespace())
  .toBase64();

Test webhooks

Use a dedicated Publish Test Notification endpoint to receive test notification. You must have configured a webhook subscription to initiate it.

Webhooks for specific payment points

It is possible to provide paymentPointId when creating or updating webhooks. This results in a webhook that receives notifications only from that payment point. Webhooks without this parameter receive notifications from all payment points.

Available webhook events

Payment Points API

Event	Description
paymentpoint.activated	Published when newly created payment point is approved and ready to be used. Relevant to integrators.
Request body example { "notificationId": "946599d2-a6f2-4752-a1d0-b2454057f73e", "eventType": "paymentpoint.activated", "eventDate": "2021-10-13T11:20:53Z", "data": { "id": "403554fa-3147-4995-9668-1469039107c2b7", "type": "paymentpoint" } }

Payments API

Event	Description
payment.reserved	Published when payment has been approved by MobilePay user and is ready to be captured.
Request body example { "notificationId": "c85f42aa-0a81-4838-8e87-72236a348d08", "eventType": "payment.reserved", "eventDate": "2021-10-15T15:30:31Z", "data": { "id": "ceb351ac-9d20-4300-b5ad-e05851d5a3b7", "type": "payment", "reference": "My-Payment-1" } }
payment.cancelled_by_user	Published when payment has been cancelled by user inside MobilePay app.
Request body example { "notificationId": "b0dc5f2f-a7f7-4f89-8dc4-1dde6c6cab17", "eventType": "payment.cancelled_by_user", "eventDate": "2021-10-22T15:32:14Z", "data": { "id": "1c6f866d-9633-444b-b00d-33a5a5391869", "type": "payment", "reference": "My-Payment-2" } }
payment.expired	Published when either initiated payment didn't have any user interactions for 5-10 minutes or payment was reserved, but 7 days have passed and the reservation has expired.
Request body example { "notificationId": "5fdf8922-2429-4403-9e6d-055a53ae2c11", "eventType": "payment.expired", "eventDate": "2021-10-22T15:55:05Z", "data": { "id": "37cc0040-c78a-4136-8174-3f4079b0ec9c", "type": "payment", "reference": "My-Payment-3" } }

Transfers

Event	Description
transfer.succeeded	Published when payment point balance has been successfully transferred to merchant account.
Request body example { "notificationId": "f0690087-c51a-412f-a79c-e7977409ad84", "eventType": "transfer.succeeded", "eventDate": "2022-07-13T03:14:15Z", "data": { "id": "cae32025-b2ab-4973-8603-d51f8470005e", "type": "transfer" } }

Create webhook

You can view and manage webhooks in the MobilePay portal or via Webhooks Api

When creating a webhook, you need to subscribe to events, and app payments events are available only if you have an App Payments product. The URL must be HTTPS and unique per webhook.