# Webhooks

Charges take 3-10 minutes to settle once the customer makes the payment. Once a charge is complete, you might require your internal systems and databases to be updated. You may also wish to take appropriate actions such as dispatching the order and updating inventory.

Webhooks can be used to facilitate communication between your system and XanPay. They can notify your system and execute appropriate logic. This documentation explains how to set up webhooks.

# Set up an endpoint

A webhook is an HTTP endpoint that receives notifications. Begin by setting up an HTTP endpoint on your server which will process notifications from XanPay. When the status of a charge changes, XanPay will send an HTTP POST request to your endpoint. Your endpoint must check authorization and process the details sent in the request.

# Basic Authorization

The username and password should be used by your endpoint to authenticate incoming requests from XanPay. While calling a your webhook URL, we send the HTTP Basic Authorization (opens new window) header with username:password encoded in base64 to help secure the request. We expect that your API decodes this string and checks the username and password parameters to protect itself from unauthorized calls.

# Request body

The format of the request body we send to your endpoint is as follows. Your endpoint should process this format and retrieve relevant information.

  "timestamp": 1618226757.504,
  "reason": "charge_status_updated",
  "payload": { 
      "chargeId": "609c80f6a5b44800116d7c16",
      "merchantId": "605015227b87ad0011c63549",
      "customerCurrency": "SGD",
      "merchantAmount": 100, 
      "merchantCurrency": "SGD",
	  "notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9", 
      "paymentMethod": "paynow", 
      "orders": [

# Charge status

The current status of the charge is reflected in the "payload"."status" argument and it's values are described here.

# Charge data

If you want your endpoint to receive additional data, such as the your internal order identifier, set the notifyPayload parameter when you are creating the charge. You can retrieve this data in the "payload"."notifyPayload" argument in the request body. This argument accepts strings. In case you wish to send an object e.g {"orderId": "251"}, you can convert it into a string by encoding into base64, e.g. "eyJvcmRlcklkIjogIjI1MSJ9". When your webhook is triggered, you can decode the notifyPayload parameter and retrieve the original object.

  • If you are using a checkout link, you can send an object with the required data in the notifyPayload parameter.

  • If you are creating a charge using the REST API, and making the following API call POST /charges request, you can send an object with the required data in the notifyPayload parameter.

# Register webhook

Once you have created an endpoint with the appropriate authentication, you can register your webhook on the XanPay dashboard (opens new window).

To register a webhook, you are required to enter the endpoint's URL, a username and a password for Basic authorization and a checkbox for adding the webhook to the Sandbox environment. UI for adding webhook

Whenever the status of a charge changes, we notify all webhooks that you have registered for the appropriate environment, Production or Sandbox.

If you choose not to use webhooks, and would still like to check charge status, you can retrieve current information regarding the charge via the REST API.

# Test webhook

We recommend testing the webhooks you set up in the dashboard. Click Send webhooks button in the Webhooks (opens new window) section to check if your webhook is being called. It is also recommend that you use Sandbox mode to test your workflow as described here.