헥토파이낸셜 개발자센터

Deposit Lookup API

This method allows merchants to perform validity checks directly without the PG provider conducting the receipt inquiry. Before a customer makes a deposit, Hecto Financial sends a receipt inquiry request to the merchant, and the merchant confirms validity and responds.

Merchant Receipt Inquiry Service Application Required

The merchant receipt inquiry feature requires a separate application. This feature is available after applying through your sales representative.

Deposit Receipt Inquiry Flow

Buyer
Bank
Hecto Financial
Merchant
11. Deposit attempt
22. Receipt inquiry request
33. Receipt inquiry message transmission
44. Validity check result response
55. Receipt inquiry result delivery
66. Deposit processing (on success)

Communication Specification

ItemDescription
Request DirectionHecto Financial → Merchant
Response DirectionMerchant → Hecto Financial
MethodPOST
Request Content-Typeapplication/x-www-form-urlencoded; charset=UTF-8
Response Content-Typeapplication/json
EncodingUTF-8 by default (if received as EUC-KR, respond with the same encoding)

Request Parameters (Hecto Financial → Merchant)

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

Parameters that Hecto Financial's server sends to the merchant.

└methodA(2)Alphabetic, up to 2 bytes*VA
Payment method
VA: Virtual Account (fixed value)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*B0
Business type
B0: Payment (fixed value)
└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxva_sb_il
Unique merchant ID assigned by Hecto Financial
└trdNoAN(40)Alphanumeric, up to 40 bytesSTFP_PGCAnxva_sb_il0211129135810M1494620
Unique transaction number issued by Hecto Financial. Required response for Rotating-type/Fixed-type; not provided for Fixed-type Recurring.
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Unique merchant order number generated by the merchant
└trdDtmN(14)Numeric, up to 14 bytes*20221105140259
Date and time the message is sent (YYYYMMDDhhmmss)
└trdAmtN(12)Numeric, up to 12 bytes*1000
Transaction amount
└bankCdAN(3)Alphanumeric, up to 3 bytes*011
Virtual account bank code
└acntTypeN(1)Numeric, up to 1 bytes*1
Account type
1: Default (Rotating-type) 2: Fixed-type 3: Fixed-type Recurring
└vAcntNoN(64)Numeric, up to 64 bytes*1234567890
Virtual account number (encrypted per merchant)
└mediaTypeN(2)Numeric, up to 2 bytes00
Code for the medium the customer used for deposit/transfer
└rcptTypeA(1)Alphabetic, up to 1 bytes*N
Receipt inquiry type code
N: Receipt Inquiry P: P Receipt Inquiry
*See the 'Receipt Inquiry Type (N / P)' section below for supported banks and the dual-send behavior.
└pktHashAN(64)Alphanumeric, up to 64 bytes*6056160d8f24c3ad15a015a0a666b5584c9471c2f8f56945482ca3e656bd0125
Hash value generated using SHA256

Request Hash Code

ItemCombination Fields
pktHashPayment method + business type + transaction date and time + merchant ID + transaction number + transaction amount + hash key
NOTE

Hash Generation Combination

method + bizType + trdDtm + mchtId + trdNo + trdAmt (plaintext) + hashKey

Media Codes

CodeNameNotes
00OtherSet to "00" when the bank does not provide information
01Same-bank counter
02Other-bank counter
03Same-bank CD/ATM
04Other-bank CD/ATM
05Telebanking
06Internet banking
07Smart banking
08Electronic financial network
09Automatic transfer depositGiro, CMS, VAN funds, payer, etc.
10Real-time transfer
11Unmanned public charges

Receipt Inquiry Type (N / P)

rcptType indicates whether this request is a regular receipt inquiry (N) or a P receipt inquiry (P).

Banks supporting P receipt inquiry may send the receipt inquiry twice

For banks that support P receipt inquiry, both a regular receipt inquiry (N) and a P receipt inquiry (P) may be sent for a single deposit, resulting in up to two receipt inquiry requests. If you do not want to receive duplicates, you can apply to receive only the P receipt inquiry (P). (Contact your sales representative.)

P Receipt Inquiry Support by Bank

Bank CodeBank NameP Receipt Inquiry
003Industrial Bank of Korea (IBK)Y
004KB Kookmin BankY
011NH NongHyup BankY
020Woori BankY
023Standard Chartered Bank KoreaN
031iM Bank (Daegu Bank)Y
032BNK Busan BankN
034Kwangju BankN
039BNK Kyongnam BankY
071Korea PostY
081Hana BankY
088Shinhan BankY
089KbankY
NOTE

Korea Post P receipt inquiry exception

Korea Post supports P receipt inquiry, but when a deposit is made via a cash-based channel such as an ATM or bank counter, a notification-type message is received instead, and the P receipt inquiry is not sent.

Response Parameters (Merchant → Hecto Financial)

Parameters that the merchant responds with to Hecto Financial.

└rsltCdN(4)Numeric, up to 4 bytes*0000
Result code
0000: Normal 0001: Account not found 0002: Deposit deadline expired 0003: Amount error 0004: Disallowed medium 0009: Other error
└rsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message
*For internal merchant reference only.

Response Result Codes

Result CodeResult MessageDescription
0000NormalReceipt inquiry successful, deposit allowed
0001Account not foundThe virtual account does not exist
0002Deposit deadline expiredThe virtual account deposit deadline has expired
0003Amount errorThe deposit amount does not match the issued amount
0004Disallowed mediumDeposits via this medium are not allowed
0009Other errorOther error occurred

Response Examples

Success

{
  "rsltCd": "0000",
  "rsltMsg": "Processed successfully."
}

Failure (Deposit Deadline Expired)

{
  "rsltCd": "0002",
  "rsltMsg": "Deposit deadline has expired."
}

Failure (Amount Error)

{
  "rsltCd": "0003",
  "rsltMsg": "Deposit amount does not match."
}

Merchant Implementation Guide

NOTE

Receipt Inquiry Processing Logic

When the merchant receives a receipt inquiry request, they must verify the validity of the order (account existence, deposit deadline, amount) and respond with the result.

Implementation Checklist

  1. Check account existence: Query the order by mchtTrdNo or vAcntNo
  2. Check deposit deadline: Verify that the current time is before the deposit deadline
  3. Check amount: Verify that trdAmt matches the amount set at issuance
  4. Hash verification: Verify pktHash value to check for data tampering

Sample Code (Node.js)

app.post('/api/receipt-inquiry', (req, res) => {
  const { mchtTrdNo, trdAmt, vAcntNo, pktHash } = req.body;

  // 1. Hash verification
  if (!verifyHash(req.body, pktHash)) {
    return res.json({ rsltCd: '0009', rsltMsg: 'Hash verification failed' });
  }

  // 2. Order inquiry
  const order = findOrderByTrdNo(mchtTrdNo);
  if (!order) {
    return res.json({ rsltCd: '0001', rsltMsg: 'Account not found' });
  }

  // 3. Check deposit deadline
  if (new Date() > order.expireDate) {
    return res.json({ rsltCd: '0002', rsltMsg: 'Deposit deadline expired' });
  }

  // 4. Check amount
  if (order.amount !== parseInt(trdAmt)) {
    return res.json({ rsltCd: '0003', rsltMsg: 'Amount error' });
  }

  // 5. Success response
  return res.json({ rsltCd: '0000', rsltMsg: 'Normal' });
});

Request/Response Examples

Receipt Inquiry Request (Hecto Financial → Merchant)

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

method=VA
&bizType=B0
&mchtId=nxva_sb_il
&trdNo=STFP_PGVAnxva_sb_il0211231100000M1234567
&mchtTrdNo=ORDER20211231100000
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&acntType=1
&vAcntNo=12345678901234
&mediaType=06
&rcptType=N
&pktHash=6056160d8f24c3ad15a015a0a666b5584c9471c2f8f56945482ca3e656bd0125

Response - Success (Merchant → Hecto Financial)

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "rsltCd": "0000",
  "rsltMsg": "Normal"
}

Response - Failure (Merchant → Hecto Financial)

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "rsltCd": "0003",
  "rsltMsg": "Amount error"
}
💬

Need technical support?