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
transfer.processingOnce the transfer is processed
transfer.scheduledOnce the transfer is scheduled
transfer.paidOnce the transfer is paid
transfer.failedOnce the transfer is failed
transfer.canceledOnce 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 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/transfer
User-AgentHitPay 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

{
  "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": "test@gmail.com",
    "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": "test@gmail.com",
      "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

{
  "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": "test@gmail.com",
    "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

CodeDescription
100101Invalid account number
100102Invalid bank branch code
100103Invalid SWIFT/BIC code
100104Invalid correspondent bank information
100105Invalid bank information
100201Beneficiary name mismatch
100202Account currency mismatch
100301Invalid beneficiary details
100302Invalid special character in beneficiary details
100401Screening error
100501Insufficient balance
100601Account closed
100602Account inactive or dormant
100603Account under restriction
100701Beneficiary requested
100702Beneficiary bank returned
100803Beneficiary account type not supported
100901Recall requested
100902Client requested
101001Invalid payment purpose
101101System error
101102Channel timeout
101201Other error

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