Skip to main content

Webhook (Notification) Service

The Webhook (Notification) Service allows the merchant's server to receive real-time notifications whenever a transaction status changes.

Important
  • Notifications are sent only for successful transactions. (Transaction rejections are not notified).
  • While HTTP is supported, we strongly recommend using HTTPS for security.

You can register your Webhook URL and select which services to receive notifications for in the Merchant Admin Console.

Retry Policy​

If the merchant server responds with a success code after receiving the webhook, no further notifications are sent. If the initial notification fails (e.g., network error, non-200 response), the system will retry up to 10 times at 3-minute intervals.

[Image of webhook retry policy flowchart]

Manual Retry

For transactions that failed all 10 automatic retries, you can manually request a resend via the Merchant Admin > Transaction Management > Notification Inquiry menu.

Response Requirement​

Your server must respond with the following JSON format to acknowledge receipt.

Webhook Response Example
{
    // If processed successfully
    "resCd": "0000",
    "resMsg": "Success"

    // If processing failed
    "resCd": "5001",
    "resMsg": "Processing Failed"
}

Firewall Policy​

Merchants using the Webhook service must configure their firewall to allow inbound traffic from the following IP addresses.

EnvironmentSource IPDescription
Production203.233.72.150INBOUND
203.233.72.151INBOUND
61.33.211.180INBOUND
Development61.33.205.151INBOUND

Event Types​

CodeEvent NameDescription
10ApprovalNotification for successful payments (Credit Card, Bank Transfer, Mobile, etc.)
20ChangeNotification for cancellations or refunds of approved transactions
30DepositNotification for Virtual Account deposits
31Deposit CancelNotification when a deposit is cancelled due to a bank error after notification
40EscrowNotification for Escrow status changes
50Refund CompleteNotification for Settlement Refund (D+1) completion
51Transfer FailedNotification when a Real-time Refund fails due to a bank error
70UnionPayNotification for UnionPay payment confirmation

Integration Guide​

HTTP Header​

The webhook is sent as a POST request with the following header.

Header Info
POST https://{Merchant Webhook URL}
Content-type: application/json; charset=utf-8

HTTP Body​

Common Parameters​

Field NameTypeLengthRequiredDescription
resCdString4Byte✅Response Code
resMsgString1000Byte✅Response Message
mallIdString8Byte✅Merchant ID assigned by KICC
notiTypeString2Byte✅Event Type Code (See Event Types table)
pgCnoString20Byte✅PG Transaction ID (Deposit Transaction ID for Virtual Account Deposits)
shopOrderNoString40Byte✅Merchant Order No.

Specific Parameters​

The following parameters are included depending on the notiType and payment method.

Field NameTypeLengthDescription
amountString12byteTotal Amount
approvalNoString20byteApproval Number
transactionDateString14byteTransaction Date/Time
pointAuthNoString15bytePoint Approval Number
pointTransactionDateString14bytePoint Approval Date/Time
cardNoString40byteCard Number
issuerCodeString3byteIssuer Code (See Card Codes)
issuerNameString20byteIssuer Name
acquirerCodeString3byteAcquirer Code (See Card Codes)
acquirerNameString20byteAcquirer Name
installmentMonthString2byteInstallment Month
freeInstallmentTypeCodeString2byteInterest-free Type (Interest: "00", Merchant-paid: "02", Card-paid: "03")
bankCodeString3byteBank Code
bankNameString20byteBank Name
accountNoString20byteAccount Number
depositNameString10byteDepositor Name
expiryDateString14byteVirtual Account Expiration Date
cashUsedString1byteCash Receipt Issued (1: Yes, 0: No)
cashResCdString4byteCash Receipt Result Code
cashResMsgString64byteCash Receipt Result Message
cashAuthNoString20byteCash Receipt Approval Number
cashTranDateString14byteCash Receipt Date/Time
cashIssueTypeString2byteCash Receipt Issue Purpose
cashAuthTypeString1byteCash Receipt Auth Type
cashAuthValueString20byteCash Receipt Identity Value
cashAmountString12byteCash Receipt Total Amount
cashTaxAmountString12byteCash Receipt Taxable Amount
cashFreeAmountString12byteCash Receipt Tax-free Amount
cashVatAmountString12byteCash Receipt VAT Amount
authIdString20bytePhoneID
billIdString20byteBill ID
mobileNoString20byteMobile Number
mobileAnsimUsedString1byteSafe Payment Used (Y/N)
cpCodeString4byteService Provider Code (See CP Codes)
pntAmountString9byteUsed Points
remainPointString9byteRemaining Points
payPntString9byteDiscount/Generated Points
accruePntString9byteAccumulated Points
deductPntString9byteTotal Deducted Points
paybackPntString9bytePayback Points
mallNameString20byteMerchant Name
escrowUsedString1byteEscrow Used (Y/N)
escrowTypeCodeString1byteEscrow Type ("K")
complexUsedString1byteComplex Payment Used (Y/N)
cancelAcqDateString14byteCapture Cancel Date/Time
cancelDateString14byteCancel Date/Time
joinNoString15byteMerchant Number
statusCodeString4byteTransaction Status Code (See Status Codes)
statusMessageString100byteStatus Message
vanTidString15byteVAN TID
vanSnoString12byteVAN Serial Number
payMethodTypeCodeString2bytePayment Method Code (See Codes)
tlfSnoString20byteVirtual Account Transaction No.
certNoString20byteARS Auth Number
partCancelUsedString1bytePartial Cancel Available (Y/N)
membGubunString1byteMerchant Type
cardGubunString1byteCard Type (Credit/Check)
cardClassString1byteEmployee Card Type
cardBizGubunString1byteCard Owner Type (Personal/Corporate)
couponFlagString1byteCoupon/Instant Discount Used (Y/N)
cponAuthNoString20byteCoupon Approval Number
cponTranDateString14byteCoupon Approval Date/Time
remainCponString9byteCoupon Balance
couponAmountString9byteCoupon Discount Amount
cancelAmountString12bytePartial Cancel/Refund Amount
cancelCardAmountString12byteCancelled Card Amount
cancelCouponAmountString12byteCancelled Coupon Amount
cancelPgCnoString20byteCancel/Refund PG Transaction ID
cardnoHashString44byteCard Number Hash
vcntTypeString1byteVirtual Account Type
customerNameString20byteCustomer Name
vpCardcodeString15byteVP Card Code
taxFlgString4byteComplex Tax Flag ("TG01")
taxAmountString12byteTaxable Amount
freeAmountString12byteTax-free Amount
vatAmountString12byteVAT Amount
cponTermsString12byteDiscount Standard Amount
cancelRemainAmountString12byteRemaining Amount after Cancel
shopValue1String1000byteCustom Field 1
shopValue2String100byteCustom Field 2
shopValue3String100byteCustom Field 3
shopValue4String100byteCustom Field 4
shopValue5String100byteCustom Field 5
shopValue6String100byteCustom Field 6
customerIdString20byteCustomer ID
cardAmountString12byteCredit Card Approval Amount
cancelPointAmountString12byteCancelled Point Amount
depositPgCnoString20byte(Refund) Virtual Account Deposit Transaction ID
depoBkcdString3ByteDeposit Bank Code
depoBknmString20ByteDeposit Bank Name
dayRemPntString9byteDaily Remaining Points
monthRemPntString9byteMonthly Remaining Points
dayRemCntString9byteDaily Remaining Limit Count
remainAmountString12byteRemaining Prepaid Balance
multiCardAmountString12byteMulti-pay Card Amount (Approve/Cancel)
multiPntAmountString12byteMulti-pay Point Amount (Approve/Cancel)
multiCponAmountString12byteMulti-pay Coupon Amount (Approve/Cancel)
subCardCdString3byteSub Card Code
cardMaskNoString40byteMasked Card Number
oilMgrCostString9byteFuel Unit Price
oilMgrVolumeString9byteFuel Volume
oilPayTypeString1byteFuel Pre-payment Method
mobileCdString3byteMobile Carrier Code
basketUsedString1ByteBasket (Split Settlement) Used (Y/N)
bkResCntString2ByteBasket Item Count (Max 20)
productNo[1-20]String40ByteProduct Order No
productPgCno[1-20]String20ByteProduct PG Transaction ID
sellerId[1-20]String40ByteSeller ID

Payload Examples by Event Type​

Same parameters as the general payment approval response.

{
  "resCd": "0000",
  "resMsg": "Success",
  "mallId": "{Merchant ID}",
  "notiType": "10",
  "pgCno": "{PG Transaction ID}",
  "shopOrderNo": "{Merchant Order No}",
  "amount": "1200",
  "approvalNo": "01230000",
  "transactionDate": "20251105092752",
  "cardNo": "49000000****050*",
  "issuerCode": "027",
  "issuerName": "Hyundai Visa Personal",
  "acquirerCode": "027",
  "acquirerName": "Hyundai Card",
  "freeInstallmentTypeCode": "00",
  "installmentMonth": "00",
  "pntAmount": "0",
  "escrowUsed": "N",
  "complexUsed": "N",
  "statusCode": "TS03",
  "statusMessage": "Capture Requested",
  "vanTid": "7574638",
  "vanSno": "807627429171",
  "payMethodTypeCode": "11",   
  "partCancelUsed": "Y",
  "membGubun": "2",
  "cardGubun": "N",
  "cardBizGubun": "P",
  "couponFlag": "N",
  "cardnoHash": "Gy8kMh3KAAAAAT0G9u74AAAAAIUXqVcMmPy0UWAAAAA",
  "customerName": "John Doe",
  "customerId": "test",
  "basketUsed": "N"
  // ...
}