헥토파이낸셜 개발자센터

Credit Card Webhook

When a transaction is successfully completed, Hecto Financial sends a webhook to your server. For details, see the notiUrl guide.

NOTE

What is notiUrl?

notiUrl is a server-to-server webhook that sends the payment result directly from the Hecto Financial server to your server. It does not go through the browser, ensuring reliable delivery of payment results.

Communication Specification

ItemDescription
MethodPOST
Content-Typeapplication/x-www-form-urlencoded; charset=UTF-8
Response FormatPlain Text (OK or FAIL)

Cancellation Webhook Notice

Cancellation webhook is not provided by default

Credit card cancellation results are confirmed via API response, so cancellation webhooks are not sent by default. If you need cancellation webhooks, contact your sales representative or technical support (pgsupport@hecto.co.kr).

Webhook Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└outStatCdN(4)Numeric, up to 4 bytes*0021
Transaction status
0021: Success
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCAnxca_jt_il0211129135810M1494620
Unique transaction number assigned by Hecto Financial
└methodA(2)Alphabetic, up to 2 bytes*CA
Payment method
CA: Credit Card
└bizTypeAN(2)Alphanumeric, up to 2 bytes*B0
Business type
B0: Approval C0: Cancellation
└mchtIdAN(12)Alphanumeric, up to 12 bytes*nxca_jt_il
Merchant ID assigned by Hecto Financial
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Unique order number generated by the merchant
└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesHong Gil-dong
The name of the customer who completed this payment
└mchtNameAHN(20)Alphanumeric + Korean, up to 20 bytesHecto Financial
Actual seller name. If not provided, the merchant name registered with Hecto Financial is used.
└pmtprdNmAHN(128)Alphanumeric + Korean, up to 128 bytesTest Product
Product name ordered by the customer
└trdDtmN(14)Numeric, up to 14 bytes*20211231100000
Transaction datetime. For approvals: approval datetime. For cancellations: cancellation datetime. Format: YYYYMMDDhhmmss
└trdAmtN(12)Numeric, up to 12 bytes1000
Transaction amount
└svcAmtN(12)Numeric, up to 12 bytes0
Credit card service charge. Provided only for offline transactions that include a service charge.
└billKeyAN(40)Alphanumeric, up to 40 bytesSBILL_0123456789
Billkey issued for subsequent recurring charges
└billKeyExpireDtN(4)Numeric, up to 4 bytes2212
Billkey expiration date (YYMM)
└cardCdAN(10)Alphanumeric, up to 10 bytesNHC
Card company code
*Sent based on the card issuer.
See the Card Company Code Reference page for card company codes.
└cardNmAHN(20)Alphanumeric + Korean, up to 20 bytesNH Check
Card company name
└emailAN(60)Alphanumeric, up to 60 bytesHongGilDong@example.com
Merchant customer email
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesHongGilDong
Merchant customer ID
└cardNoAN(20)Alphanumeric, up to 20 bytes123456******7890
Masked card number (optional based on merchant settings)
*App card and digital wallet cards may differ from the actual card number.
└cardApprNoAN(15)Alphanumeric, up to 15 bytes30001234
Card approval number
└instmtMonN(2)Numeric, up to 2 bytes00
Installment months
└instmtTypeA(1)Alphabetic, up to 1 bytesN
Indicates whether the installment is interest-free under a card issuer promotional plan. 'Y' = promotional zero-interest installment; 'N' = standard installment. Included only when enabled for your merchant account.
└orgTrdNoAN(40)Alphanumeric, up to 40 bytesSTFP_PGCAnxca_jt_il0211129135810M1494620
Original transaction number for cancellations
└orgTrdDtN(8)Numeric, up to 8 bytes20211231
Original transaction date for cancellations
└mixTrdNoAN(40)Alphanumeric, up to 40 bytesSTFP_PGCAnxca_jt_il0211129135810M1494620
Combined payment transaction number
└mixTrdAmtN(12)Numeric, up to 12 bytes1000
Combined payment amount. Provided only when mixTrdNo exists.
└payAmtN(12)Numeric, up to 12 bytes1000
Actual payment amount excluding combined payment amount (payAmt = trdAmt - mixTrdAmt). Provided only when mixTrdNo exists.
└cnclTypeN(2)Numeric, up to 2 bytes00
Cancellation type
00: Full cancellation 10: Partial cancellation
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesname=HongGilDong&age=25
Additional merchant information field. The value passed in the request is returned as-is.
└pktHashAN(64)Alphanumeric, up to 64 bytes*a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1
Request signature (SHA-256) used to verify that this webhook was sent by Hecto Financial. Always verify this value before processing the webhook.
NOTE

Hash Generation Combination

outStatCd + transaction date (first 8 digits of trdDtm) + transaction time (last 6 digits of trdDtm) + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey
└vatN(12)Numeric, up to 12 bytes91
VAT amount
*For offline PG only; availability varies by VAN provider.
└taxAmtN(12)Numeric, up to 12 bytes909
Taxable amount
*For offline PG only; availability varies by VAN provider.
└taxFreeAmtN(12)Numeric, up to 12 bytes0
Tax-free amount
*For offline PG only; availability varies by VAN provider.
└acqrCdAN(4)Alphanumeric, up to 4 bytesNICE
Acquirer code
*For offline PG only; availability varies by VAN provider.
└bizRegNoAN(10)Alphanumeric, up to 10 bytes1234567890
Merchant business registration number
*For offline PG only; availability varies by VAN provider.
└joinNoAN(30)Alphanumeric, up to 30 bytes123456789
Merchant number
*For offline PG only; availability varies by VAN provider.

Webhook Response (Merchant → Hecto Financial)

Your server sends a response to Hecto Financial.

ResponseDescription
OKSuccess (uppercase). Processed as webhook received.
FAILRecognized as an explicit failure (uppercase). The webhook is resent.
OthersRecognized as an abnormal failure; resent up to the configured number of times per merchant. Sending stops after exceeding the resend deadline.

Response format note

The response must be plain text 'OK' only. If spaces or other characters are included, it will be considered a failure and resending will occur.

Hash Verification

Hash verification required

To check for data tampering, you must verify the hash data received via notiUrl. Only provide the service when the hash matches.
// Node.js hash verification example
const crypto = require('crypto');

function verifyHash(data, hashKey) {
    const { outStatCd, trdDtm, mchtId, mchtTrdNo, trdAmt, pktHash } = data;
    const trdDt = trdDtm.substring(0, 8);  // YYYYMMDD
    const trdTm = trdDtm.substring(8, 14); // HHmmss

    const hashString = outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt + hashKey;
    const calculatedHash = crypto.createHash('sha256').update(hashString, 'utf8').digest('hex');

    return pktHash === calculatedHash;
}

Webhook Example

Approval Webhook (Hecto Financial → Merchant)

POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

outStatCd=0021
&trdNo=STFP_PGCAnxca_jt_il0211231100000M1234567
&method=CA
&bizType=B0
&mchtId=nxca_jt_il
&mchtTrdNo=ORDER20211231100000
&mchtCustNm=HongGilDong
&mchtName=HectoFinancial
&pmtprdNm=Test Product
&trdDtm=20211231100000
&trdAmt=50000
&cardCd=HDC
&cardNm=HyundaiCard
&cardNo=123456******7890
&cardApprNo=30001234
&instmtMon=00
&instmtType=N
&email=test@example.com
&mchtCustId=customer123
&mchtParam=
&pktHash=a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1

Response (Merchant → Hecto Financial)

OK

After Receiving the Webhook

  1. Verify pktHash to confirm the webhook is from Hecto Financial.
  2. Check outStatCd: 0021 = payment successful; 0031 = payment failed.
  3. Match mchtTrdNo to your stored order and update the order status.
  4. Always return the plain text OK response — even for failed payments — to stop retry attempts.
💬

Need technical support?