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.
NOTE
When paid via simple payment
If the customer pays with a simple payment (KakaoPay, NaverPay, etc.) on the credit card checkout, the result is delivered as a simple payment webhook with the payment method code PZ. See the simple payment webhook document below for parameters. View the simple payment webhook
Communication Specification
| Item | Description |
|---|---|
| Method | POST |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| Response Format | Plain 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*Transaction status
0021Transaction status
0021: Success└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number assigned by Hecto Financial
STFP_PGCAnxca_jt_il0211129135810M1494620Unique transaction number assigned by Hecto Financial
└methodA(2)Alphabetic, up to 2 bytes*Payment method
CAPayment method
CA: Credit Card└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type
B0Business type
B0: Approval C0: Cancellation A8: Billkey issuance└mchtIdAN(12)Alphanumeric, up to 12 bytes*Merchant ID assigned by Hecto Financial
nxca_jt_ilMerchant ID assigned by Hecto Financial
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant
ORDER20211231100000Unique order number generated by the merchant
└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesThe name of the customer who completed this payment
Hong Gil-dongThe name of the customer who completed this payment
└mchtNameAHN(20)Alphanumeric + Korean, up to 20 bytesActual seller name. If not provided, the merchant name registered with Hecto Financial is used.
Hecto FinancialActual seller name. If not provided, the merchant name registered with Hecto Financial is used.
└pmtprdNmAHN(128)Alphanumeric + Korean, up to 128 bytesProduct name ordered by the customer
Test ProductProduct name ordered by the customer
└trdDtmN(14)Numeric, up to 14 bytes*Transaction datetime. For approvals: approval datetime. For cancellations: cancellation datetime. Format: YYYYMMDDhhmmss
20211231100000Transaction datetime. For approvals: approval datetime. For cancellations: cancellation datetime. Format: YYYYMMDDhhmmss
└trdAmtN(12)Numeric, up to 12 bytesTransaction amount
1000Transaction amount
└svcAmtN(12)Numeric, up to 12 bytesCredit card service charge. Provided only for offline transactions that include a service charge.
0Credit card service charge. Provided only for offline transactions that include a service charge.
└billKeyAN(40)Alphanumeric, up to 40 bytesBillkey issued for subsequent recurring charges
SBILL_0123456789Billkey issued for subsequent recurring charges
└billKeyExpireDtN(4)Numeric, up to 4 bytesBillkey expiration date (YYMM)
2212Billkey expiration date (YYMM)
*Provided only to merchants with a prior agreement
└cardCdAN(10)Alphanumeric, up to 10 bytesCard company code
NHCCard company code
*Sent based on the card issuer.
See the Card Company Code Reference page for card company codes.
See the Card Company Code Reference page for card company codes.
└cardNmAHN(20)Alphanumeric + Korean, up to 20 bytesCard company name
NH CheckCard company name
└emailAN(60)Alphanumeric, up to 60 bytesMerchant customer email
HongGilDong@example.comMerchant customer email
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesMerchant customer ID
HongGilDongMerchant customer ID
└cardNoAN(20)Alphanumeric, up to 20 bytesMasked card number (optional based on merchant settings)
123456******7890Masked 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 bytesCard approval number
30001234Card approval number
└instmtMonN(2)Numeric, up to 2 bytesInstallment months
00Installment months
└instmtTypeA(1)Alphabetic, up to 1 bytesIndicates 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.
NIndicates 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 bytesOriginal transaction number for cancellations
STFP_PGCAnxca_jt_il0211129135810M1494620Original transaction number for cancellations
└orgTrdDtN(8)Numeric, up to 8 bytesOriginal transaction date for cancellations
20211231Original transaction date for cancellations
└mixTrdNoAN(40)Alphanumeric, up to 40 bytesCombined payment transaction number
STFP_PGCAnxca_jt_il0211129135810M1494620Combined payment transaction number
└mixTrdAmtN(12)Numeric, up to 12 bytesCombined payment amount. Provided only when mixTrdNo exists.
1000Combined payment amount. Provided only when mixTrdNo exists.
└payAmtN(12)Numeric, up to 12 bytesActual payment amount excluding combined payment amount (payAmt = trdAmt - mixTrdAmt). Provided only when mixTrdNo exists.
1000Actual payment amount excluding combined payment amount (payAmt = trdAmt - mixTrdAmt). Provided only when mixTrdNo exists.
└cnclTypeN(2)Numeric, up to 2 bytesCancellation type
00Cancellation type
00: Full cancellation 10: Partial cancellation└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesAdditional merchant information field. The value passed in the request is returned as-is.
name=HongGilDong&age=25Additional merchant information field. The value passed in the request is returned as-is.
└pktHashAN(64)Alphanumeric, up to 64 bytes*Request signature (SHA-256) used to verify that this webhook was sent by Hecto Financial. Always verify this value before processing the webhook.
a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1Request 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 bytesVAT amount
91VAT amount
*For offline PG only; availability varies by VAN provider.
└taxAmtN(12)Numeric, up to 12 bytesTaxable amount
909Taxable amount
*For offline PG only; availability varies by VAN provider.
└taxFreeAmtN(12)Numeric, up to 12 bytesTax-free amount
0Tax-free amount
*For offline PG only; availability varies by VAN provider.
└acqrCdAN(4)Alphanumeric, up to 4 bytesAcquirer code
NICEAcquirer code
*For offline PG only; availability varies by VAN provider.
└bizRegNoAN(10)Alphanumeric, up to 10 bytesMerchant business registration number
1234567890Merchant business registration number
*For offline PG only; availability varies by VAN provider.
└joinNoAN(30)Alphanumeric, up to 30 bytesMerchant number
123456789Merchant number
*For offline PG only; availability varies by VAN provider.
Webhook Response (Merchant → Hecto Financial)
Your server sends a response to Hecto Financial.
| Response | Description |
|---|---|
OK | Success (uppercase). Processed as webhook received. |
FAIL | Recognized as an explicit failure (uppercase). The webhook is resent. |
| Others | Recognized 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
- Verify
pktHashto confirm the webhook is from Hecto Financial. - Check
outStatCd:0021= payment successful;0031= payment failed. - Match
mchtTrdNoto your stored order and update the order status. - Always return the plain text
OKresponse — even for failed payments — to stop retry attempts.
Need technical support?
Code Samples
HectoFinancial GitHub