If you are using Payment Request APIs, we suggest using the “webhook” parameter and webhook v1

​
Overview

HitPay provides event webhooks that are HTTP post requests triggered after key events that happen on the hitpay platform. These webhooks can be used to build your own automation and processes.

​
List of Events

These are the list of events you can listen to

Event NameWhen does it trigger?
charge.createdOnce a payment is successfully completed
charge.updatedOnce a payment is refunded / partially refunded
payout.createdOnce a payout is successfully completed
order.createdOnce an order is created successfully
order.updatedOnce an order status is updated
invoice.createdOnce the invoice is created
transfer.createdOnce the transfer is created
transfer.updatedOnce the transfer is updated

​
Register Your Webhook

The first thing you need to do before you can receive the webhook is to register the URL. Navigate to “API Keys” and enter the name and the URL you wish to receive the webhook.

Hero Dark

​
Webhook Payload

Headers that are included in the webhook HTTP POST request

HTTP headerdetails
Hitpay-SignatureSHA 256 of the JSON payload. Derived from the salt value
Hitpay-Event-Typecreated / updated based on the event
Hitpay-Event-ObjectThe type of object. It can be charge/payout/invoice/order
User-AgentHitPay v2.0

HTTP request body is a JSON object and the object structure can be any of the above 4 types. Refer to the header value Hitpay-Event-Objectto determine the object type

{
  "id": "98f18bb9-42a3-4cd2-a263-b6ed7d49a1cc",
  "business_id": "9130c422-bf97-4bd1-b370-07a3a6f40708",
  "channel": "point_of_sale",
  "customer_id": null,
  "status": "succeeded",
  "customer": null,
  "currency": "sgd",
  "amount": 1.11,
  "refunded_amount": 0,
  "refunded_at": null,
  "fixed_fee": 0.6,
  "discount_fee": 0.04,
  "discount_fee_rate": 3.65,
  "failed_reason": null,
  "order": {
    "id": "98f18bb8-08b8-4cec-bb3c-f2c9c90103aa",
    "order_display_number": 3350,
    "business_id": "9130c422-bf97-4bd1-b370-07a3a6f40708",
    "channel": "quick_sale",
    "version": "2.0",
    "customer_id": null,
    "business_customer_id": null,
    "customer": null,
    "customer_pickup": false,
    "currency": "sgd",
    "order_discount_name": null,
    "status": "requires_business_action",
    "remark": null,
    "products_count": 0,
    "created_at": "2023-04-16T15:59:46+08:00",
    "updated_at": "2023-04-16T15:59:55+08:00",
    "closed_at": null,
    "location_id": "97062e9f-3f27-443c-900f-16186f0540e1",
    "location": {
      "id": "97062e9f-3f27-443c-900f-16186f0540e1",
      "name": "Location 5"
    },
    "business_user_id": "34",
    "slot_date": null,
    "slot_time": null,
    "messages": null,
    "products": [],
    "charges": [],
    "line_items": [
      {
        "id": "98f18bb8-9e85-425f-b0f9-60fa54219297",
        "name": "Quick Sale",
        "item_type": "quick_sale",
        "quantity": 1,
        "related_id": "98f18bb8-08b8-4cec-bb3c-f2c9c90103aa",
        "unit_price": 1.11,
        "line_item_amount": 1.11,
        "children": []
      }
    ],
    "order_form": [],
    "order_form_response": [],
    "payment_status": "paid",
    "fulfilment_status": "Pending - Shipping",
    "line_items_total": 1.11,
    "order_discount_amount": 0,
    "line_item_discount_amount": 0,
    "line_item_tax_amount": 0,
    "additional_discount_amount": 0,
    "total_discount_amount": 0,
    "line_item_price": 0,
    "shipping_amount": 0,
    "total_coupon_amount": 0,
    "amount": 1.11,
    "subtotal": 1.11
  },
  "order_id": "98f18bb8-08b8-4cec-bb3c-f2c9c90103aa",
  "remark": null,
  "payment_intents": [],
  "payment_provider": {
    "code": "stripe_sg",
    "account_id": "acct_1GT5CuAkj749QHik",
    "charge": {
      "type": "charge",
      "id": "ch_3MxQUxAMHowMCIhZ0bU4tKfe",
      "method": "card_present",
      "transfer_type": "application_fee",
      "details": {
        "brand": "Visa",
        "last4": "4242",
        "country": null,
        "country_code": "US"
      }
    }
  },
  "created_at": "2023-04-16T15:59:47+08:00",
  "updated_at": "2023-04-16T15:59:58+08:00",
  "closed_at": "2023-04-16T15:59:55+08:00",
  "location_id": "97062e9f-3f27-443c-900f-16186f0540e1",
  "location": {
    "id": "97062e9f-3f27-443c-900f-16186f0540e1",
    "name": "Location 5"
  },
  "business_user_id": "34",
  "business_user_display": "Nitin Muthyala Test1",
  "terminal_id": "WPC32SIMULATOR1",
  "name": "Location 5"
}

​
Validating Webhook

To validate a Hitpay-Signature:

  1. Collect Data: Receive the JSON payload and the Hitpay-Signature from the incoming request.
  2. Prepare Key: Use your pre-shared salt value as the secret key.
  3. Compute HMAC: Generate an HMAC using the SHA-256 algorithm, the JSON payload as the data, and your salt as the key.
  4. Compare Signatures: Compare the computed HMAC to the Hitpay-Signature received. If they match, the request is valid and has not been tampered with.

Was this page helpful?

In Person PaymentsRecurring Billing