Webhooks

Listen to key events in HitPay including payments, orders and more

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 Name	When does it trigger?
charge.created	Once a payment is successfully completed
charge.updated	Once a payment is refunded / partially refunded
payout.created	Once a payout is successfully completed
order.created	Once an order is created successfully
order.updated	Once an order status is updated
invoice.created	Once the invoice is created
transfer.created	Once the transfer is created
transfer.updated	Once the transfer is updated
transfer.processing	Once the transfer is processed
transfer.scheduled	Once the transfer is scheduled
transfer.paid	Once the transfer is paid
transfer.failed	Once the transfer is failed
transfer.canceled	Once the transfer is canceled
payment_request.completed	Once the payment request has been paid
payment_request.failed	Once the payment request received an error
recurring_billing.method_attached	Once a payment method is attached to a subscription
recurring_billing.method_detached	Once a payment method (APMs) is detached from a subscription
recurring_billing.subscription_updated	Once a subscription is updated, including status changes (active, cancelled, paused, expired) and edits made via the dashboard

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.

Platform webhooks

Converting to a Platform Account does not automatically start sending webhooks. The platform must register webhook endpoints on its own HitPay account first.

For sub-account payments created via Platform APIs (requests include both X-BUSINESS-API-KEY for the sub-account and X-PLATFORM-KEY for the platform):

• Successful/failed charge events (charge.created, charge.failed, charge.updated) are delivered to webhook endpoints registered on the platform account — not the sub-account’s endpoints.
• The payload is for the sub-account’s transaction; use the charge or payment-request data (and business_id in the payload) to identify which sub-account it belongs to.
• Payment request events (payment_request.completed, payment_request.failed) are currently sent to the sub-account’s registered webhook endpoints.

Webhook Payload

Headers that are included in the webhook HTTP POST request

HTTP header	details
Hitpay-Signature	HMAC-SHA256 of the raw JSON body, using that webhook endpoint’s salt
Hitpay-Event-Type	created / updated based on the event
Hitpay-Event-Object	The type of object. It can be charge/payout/invoice/order/transfer
User-Agent	HitPay v2.0

HTTP request body is a JSON object and the object structure can be any of the above 5 types. Refer to the header value Hitpay-Event-Objectto determine the object type of webhooks for charge payout invoice order transfer

Event examples for charge invoice order

charge.created

{
  "id": "9e9a3451-a3e5-4fc5-9dfc-bc75e67c8808",
  "business_id": "98567029-f559-49f9-916b-042a4255b32a",
  "channel": "point_of_sale",
  "customer_id": "9b3503bd-fd04-4e39-9271-b2bc26fa5c96",
  "status": "succeeded",
  "customer": {
    "name": "Miss Vincent Marquardt",
    "email": "[e-mail]",
    "phone_number": "666",
    "address": {
      "street": null,
      "city": null,
      "state": null,
      "postal_code": null,
      "country": null
    }
  },
  "currency": "sgd",
  "amount": 913.84,
  "refunded_amount": 0,
  "refunded_at": null,
  "fixed_fee": 0,
  "discount_fee": 0,
  "discount_fee_rate": 0,
  "failed_reason": null,
  "order": {
    "id": "9e9a344b-2c04-44f4-b521-e36dce8f4ade",
    "order_display_number": 2766,
    "business_id": "98567029-f559-49f9-916b-042a4255b32a",
    "channel": "point_of_sale",
    "version": "2.0",
    "customer_id": "9b3503bd-fd04-4e39-9271-b2bc26fa5c96",
    "business_customer_id": "9b3503bd-fd04-4e39-9271-b2bc26fa5c96",
    "customer": {
      "name": "Miss Vincent Marquardt",
      "email": "[e-mail]",
      "phone_number": "666",
      "address": {
        "street": null,
        "building": null,
        "street_2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      }
    },
    "customer_pickup": false,
    "currency": "sgd",
    "order_discount_name": null,
    "status": "completed",
    "remark": null,
    "created_at": "2025-04-05T19:09:54+08:00",
    "updated_at": "2025-04-05T19:09:59+08:00",
    "closed_at": "2025-04-05T19:09:59+08:00",
    "location_id": "9e42e6be-2ff8-4b37-ac14-07970d2e79ca",
    "location": null,
    "business_user_id": "1306",
    "slot_date": null,
    "slot_time": null,
    "messages": null,
    "products": [],
    "charges": [],
    "line_items": [
      {
        "id": "9e9a344c-7b3c-4330-8926-0f9df43c3b08",
        "name": "POS TESTING - BLue",
        "thumbnail": null,
        "item_type": "product",
        "quantity": 1,
        "related_id": "9e4b75c4-cce6-4f08-ab71-abf8907f41a4",
        "unit_price": 913.84,
        "line_item_amount": 913.84,
        "item_unit_weight": 883,
        "params": null,
        "children": []
      }
    ],
    "order_form_response": null,
    "coupon": null,
    "pickup": null,
    "payment_status": "paid",
    "fulfilment_status": "completed",
    "fulfilment_type": "in_store",
    "line_items_total": 913.84,
    "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": 913.84,
    "shipping_amount": 0,
    "total_coupon_amount": 0,
    "amount": 913.84,
    "subtotal": 913.84
  },
  "order_id": "9e9a344b-2c04-44f4-b521-e36dce8f4ade",
  "remark": null,
  "payment_intents": [],
  "payment_request_id": null,
  "payment_request": null,
  "all_inclusive_fee": null,
  "home_currency": null,
  "payment_provider": {
    "code": "hitpay",
    "account_id": "98567029-f559-49f9-916b-042a4255b32a",
    "charge": {
      "type": "business_charge",
      "id": "9e9a3451-a3e5-4fc5-9dfc-bc75e67c8808",
      "method": "cash",
      "transfer_type": null,
      "details": null,
      "logo": "/icons/payment-methods-2/cash.png"
    }
  },
  "created_at": "2025-04-05T19:09:59+08:00",
  "updated_at": "2025-04-05T19:10:01+08:00",
  "closed_at": "2025-04-05T19:09:59+08:00",
  "location_id": "9e42e6be-2ff8-4b37-ac14-07970d2e79ca",
  "location": {
    "id": "9e42e6be-2ff8-4b37-ac14-07970d2e79ca",
    "name": "API_Location_1740101762910",
    "address": "58 Izpod Parkway, Singapore, Singapore, sg, 079903"
  },
  "business_user_id": "1306",
  "business_user_display": "TestingSG",
  "terminal_id": null,
  "relatable": null
}

Event examples for payout transfer

transfer.created

{
  "id": "9e9be893-9fee-4916-aca0-403e8e42b99e",
  "beneficiary": {
    "id": "9e25698b-6792-4ec6-aa81-f58692674171",
    "is_external": true,
    "status": "approved",
    "country": "sg",
    "currency": "sgd",
    "wallet_provider": "hitpay",
    "wallet_capability": "beneficiary",
    "transfer_method": "local",
    "nickname": null,
    "remark": null,
    "holder_name": "HONGKONG & SHANGHAI BANKING CORPORATION (HSBC)",
    "holder_type": "company",
    "bank_branch_code": "040",
    "account_number": "000123454",
    "bank_name": "MALAYAN BANKING BERHAD",
    "bank_id": "MBBESGS2[9636]",
    "email": "[e-mail]",
    "is_favourite": true,
    "created_at": "2025-02-06T17:46:57+08:00",
    "updated_at": "2025-03-22T22:42:17+08:00",
    "deleted_at": null
  },
  "payment_currency": "sgd",
  "payment_amount": 100,
  "source_currency": "sgd",
  "source_amount": 100,
  "exchange_rate": "1.00000",
  "fee_payer": "payer",
  "discount_fee_rate": 0,
  "fixed_fee": 0,
  "discount_fee": 0,
  "total_fee": 0,
  "fee_currency": "sgd",
  "remark": "123457788",
  "status": "scheduled",
  "attachment": null,
  "created_at": "2025-04-06T15:29:51+08:00"
}

Note: List of failure codes for transfer.failed event

Code	Description
100101	Invalid account number
100102	Invalid bank branch code
100103	Invalid SWIFT/BIC code
100104	Invalid correspondent bank information
100105	Invalid bank information
100106	Invalid proxy details
100107	Transaction not supported
100108	Account type not supported
100201	Beneficiary name mismatch
100202	Account currency mismatch
100301	Invalid beneficiary details
100302	Invalid special character in beneficiary details
100303	Invalid beneficiary country
100401	Screening error
100402	Regulatory restriction
100501	Insufficient balance
100601	Account closed
100602	Account inactive or dormant
100603	Account under restriction
100604	Beneficiary deceased
100701	Beneficiary requested
100702	Beneficiary bank returned
100801	China local transfer beneficiary validation error
100802	China local transfer order error
100803	Beneficiary account type not supported
100804	China company registration number error
100805	China local transfer processing failure
100901	Recall requested
100902	Client requested
101001	Invalid payment purpose
101002	Wrong amount
101003	Amount exceeds limit
101101	System error
101102	Channel timeout
101103	Bank offline
101201	Other error
101202	Duplicate payment

Event examples for payment_request

payment_request.completed

{
  "id": "9e9be893-9fee-4916-aca0-403e8e42b99e",
  "bank_name": "MALAYAN BANKING BERHAD",
  "bank_swift_code": "MBBESGS2XXX",
  "bank_account_number": "000123454",
  "currency": "sgd",
  "amount": 100,
  "status": "succeeded",
  "created_at": "2025-04-06T15:29:51+08:00"
}

Validating Webhook

HitPay uses two different salt values depending on the integration. Use the right one for the callback you are handling.

API-key salt (Developers page)

This salt belongs to your business API key and is shown on the Developers page alongside your API key.

It signs older payment-request and charge callbacks, plus plugin integrations—the API-driven payment flow where an hmac value is returned with the payment status.

Used for:

• Payment Request webhook and redirect callbacks
• Recurring payment callbacks
• Order and checkout callbacks (Shop, Order webhook, Hardware order)
• Plugin HMAC validation (Shopify, Wix, Xero)

How it works: Sort and concatenate the callback parameters, then compute HMAC-SHA256 using the API-key salt. The signature is sent in the hmac field in the payload, not in a header.

Per-webhook salt (Developers → Webhooks)

Each webhook endpoint you register under Developers → Webhooks has its own salt. This is the salt for event webhooks on this page (for example charge.completed, order.updated).

How it works: Compute HMAC-SHA256 of the raw request body using that webhook’s salt. The signature is sent in the Hitpay-Signature header.

Find the salt on the webhook’s detail view in the dashboard after you create the webhook endpoint.

The differences

	API-key salt	Per-webhook salt
Scope	One per business API key	One per webhook endpoint
Used for	Payment-request, charge, and plugin callbacks	Event webhooks
Signature in	hmac field in the payload	Hitpay-Signature header
What’s signed	Sorted and concatenated parameters	Raw JSON body

The steps below apply to event webhooks and use the per-webhook salt.

Validate Hitpay-Signature

1. Collect data: Read the raw JSON body and the Hitpay-Signature header from the incoming request.
2. Prepare key: Use the salt for that webhook endpoint (from Developers → Webhooks), not the API-key salt on the main Developers page.
3. Compute HMAC: Generate HMAC-SHA256 over the raw body bytes with that webhook’s salt as the key.
4. Compare signatures: Compare the computed HMAC to Hitpay-Signature. If they match, the request is authentic and unmodified.

PHP

function validateWebhook($payload, $signature, $salt) {
    $computedSignature = hash_hmac('sha256', $payload, $salt);
    return hash_equals($computedSignature, $signature);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_HITPAY_SIGNATURE'];
$salt = 'your_webhook_salt_from_dashboard';

if (validateWebhook($payload, $signature, $salt)) {
    $data = json_decode($payload, true);
// Process the event
} else {
http_response_code(401);
exit('Invalid signature');
}