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
invoice.updatedOnce the invoice is marked as paid or partially paid

Register Your Webhook

The first thing you need to do before you can receive the webhook is to register the URL. Navigate to “Payment Gateway > 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"
}