S2S Webhooks (Payments)

Omniware pushes payment and settlement events as POST requests with JSON bodies to URLs you configure in the dashboard.

See Webhooks (concept) for the cross-cutting model. This page documents the payloads for the Payments product.

Configuring callback URLs

Register your endpoints in the Omniware dashboard, one URL per event family:

Dashboard parameter	Fires on
Payment Callback URL	Every customer payment that reaches a terminal state.
Settlement Callback URL	Every settlement Omniware credits to your bank account.

If you can't find either field in the dashboard, contact your Omniware relationship manager to have them provisioned.

Payment event

Fires when a transaction reaches a terminal state (success, failure, or cancellation). The payload is the same shape as the Payment Request response — per the PDF, the S2S body is "very same response that we send as response to paymentrequest API."

{
  "transaction_id": "HDVISC1299876438",
  "payment_method": "Credit Card",
  "payment_datetime": "01-03-2024 16:45:39",
  "response_code": 0,
  "response_message": "success",
  "order_id": "ORD-1001",
  "amount": "149.00",
  "currency": "INR",
  "description": "Order 1001",
  "name": "Amit Kumar",
  "email": "amit@example.com",
  "phone": "9900990099",
  "address_line_1": "Address Line 1",
  "address_line_2": "Address Line 2",
  "city": "Bangalore",
  "state": "Karnataka",
  "country": "IND",
  "zip_code": "560001",
  "udf1": null, "udf2": null, "udf3": null, "udf4": null, "udf5": null,
  "hash": "..."
}

response_message is success or failure (lowercase in the webhook). response_code of 0 is success; non-zero values map to error codes.

note

If your merchant account is enabled for them, the webhook also includes tdr_amount, tax_on_tdr_amount, amount_orig, and cardmasked. Speak to your relationship manager if you want any of those surfaced.

Settlement event

Fires when a settlement batch is credited to your bank account. Per PDF Section 12.2, the payload mirrors the Get Settlements response — every field documented there appears in the webhook body.

{
  "settlement_id": 10075,
  "bank_reference": "710061536126",
  "payout_amount": "2.06",
  "completed": "y",
  "account_name": "Tester Sharma",
  "account_number": "50100012341231",
  "ifsc_code": "HDFC0000002",
  "bank_name": "HDFC BANK",
  "settlement_datetime": "2017-02-20 16:31:28",
  "sale_amount": "3.00",
  "chargeback_amount": "0.00",
  "refund_amount": "0.00",
  "hash": "..."
}

Field	Description
settlement_id	Aggregated settlement ID.
bank_reference	UTR / bank reference number for the NEFT/IMPS/RTGS that credited your account.
payout_amount	Net amount credited to your bank.
completed	y once the funds have actually moved.
account_name / account_number / ifsc_code / bank_name	Your settlement bank account.
settlement_datetime	When the batch was processed.
sale_amount	Gross of all transactions in this batch.
chargeback_amount	Deducted for chargeback adjustments.
refund_amount	Deducted for refund adjustments.

Verifying the hash

The hash covers SHA512(salt + json_of_body_without_hash) uppercased.

import crypto from "node:crypto";

app.post("/webhooks/omniware/payments", express.json(), (req, res) => {
  const sent = req.body.hash;
  const { hash, ...rest } = req.body;
  const computed = crypto
    .createHash("sha512")
    .update(process.env.OMNIWARE_SALT + JSON.stringify(rest))
    .digest("hex")
    .toUpperCase();

  if (!sent || !crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(computed))) {
    return res.status(400).end();
  }

  // Idempotency: dedupe by transaction_id or settlement_id.
  await markPaid(req.body.order_id, req.body.transaction_id);
  res.sendStatus(200);
});

Acknowledgement

Your response	Omniware action
2xx	Acknowledged. No retry.
Anything else (4xx, 5xx, timeout)	Not acknowledged.

Return 2xx only after hash verification and idempotent storage. The Payment Gateway PDF does not specify retry timing for failed webhook delivery, so confirm the replay policy with Omniware before relying on automatic retries. Reconciling with Payment Status on a schedule is a safe fallback.