Webhooks (notiUrl)

When a payment is completed, Hecto Financial's server sends the result directly to your server. This is called a webhook.

How Webhooks Work

There are two ways to receive payment results.

Communication Specification

All payment methods use the same specification.

Response Handling

Hash Verification

Hash verification is required to prevent data tampering.

Hash Generation Rules

SHA256(outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt (unencrypted) + licenseKey)

Verification Example (Node.js)

const crypto = require('crypto');

function verifyNoti(data, licenseKey) {
  const { outStatCd, trdDtm, mchtId, mchtTrdNo, trdAmt, pktHash } = data;

  // Split date/time from trdDtm
  const trdDt = trdDtm.substring(0, 8);   // YYYYMMDD
  const trdTm = trdDtm.substring(8, 14);  // HHmmss

  // Generate hash
  const hashString = outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt + licenseKey; // trdAmt must be the plaintext (unencrypted) amount
  const calculatedHash = crypto.createHash('sha256').update(hashString, 'utf8').digest('hex');

  return pktHash === calculatedHash;
}

// Usage example
app.post('/noti/hecto', (req, res) => {
  if (!verifyNoti(req.body, HECTO_LICENSE_KEY)) {
    console.error('Hash verification failed');
    return res.send('FAIL');
  }

  // Payment processing logic...

  res.send('OK');
});

After Successful Verification

Once hash verification passes, your webhook handler should:

1. Check outStatCd — 0021 means payment succeeded; 0031 means payment failed. Always return OK for both outcomes to prevent re-delivery.
2. Prevent duplicate processing — Check mchtTrdNo against your database before updating order status.
3. Update order status — On 0021, mark the order as paid and trigger fulfillment (inventory, shipping, email confirmation).
4. Handle failures gracefully — On 0031, update the order status to failed and notify the customer if needed.

app.post('/noti/hecto', (req, res) => {
  if (!verifyNoti(req.body, HECTO_LICENSE_KEY)) {
    console.error('Hash verification failed');
    return res.send('FAIL');
  }

  const { outStatCd, mchtTrdNo } = req.body;

  // Prevent duplicate processing
  if (await isAlreadyProcessed(mchtTrdNo)) {
    return res.send('OK');
  }

  if (outStatCd === '0021') {
    await markOrderAsPaid(mchtTrdNo);
    await triggerFulfillment(mchtTrdNo);
  } else {
    await markOrderAsFailed(mchtTrdNo);
  }

  // Always return OK to stop retry attempts
  res.send('OK');
});

notiUrl Requirements

• HTTPS is required (HTTP is not supported)
• URL must be accessible from external networks
• Hecto Financial IPs must be allowed through the firewall

Frequently Asked Questions

Webhooks are not being received

1. Verify that the notiUrl is accessible from external networks
2. Verify that the HTTPS certificate is valid
3. Check firewall settings
4. Verify that OK is returned as Plain Text in the response

Receiving duplicate webhooks

If OK is not returned in the response, the webhook will be resent. Check the response format.

When are cancellation webhooks sent?

Cancellation webhooks are not sent by default.

Since the result is received immediately in the response when calling the cancellation API, a separate webhook is not needed.

However, when cancellation is performed directly from the merchant admin panel, your server has no way of knowing the payment status, so it is possible to configure cancellation webhooks to be sent. If you need to receive cancellation webhooks, please request the configuration from your sales representative.

When cancellation webhook delivery is configured, it is sent to the notiUrl of the original transaction by default. If notiUrl was not set for the original transaction, please also provide a URL for cancellation webhooks.

Need technical support?

pgsupport@hecto.co.kr

Code Samples

HectoFinancial GitHub