Webhooks

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

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 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

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.

Webhook Payload

Headers that are included in the webhook HTTP POST request

HTTP header	details
Hitpay-Signature	SHA 256 of the JSON payload. Derived from the salt value
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

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.

Assistant

Responses are generated using AI and may contain mistakes.