跳到主要内容

通知参数

回调URL必须由商家提供。

Method POST

URL
https://xxx/xxx/paymentNotification
字段名是否必需类型描述
Signature是String包含消息的签名值。消息的发起者负责生成签名，而消息的接收者必须验证签名，以确保消息的完整性、真实性和不可否认性。

请参考 附录 1
sourceSystem是String消息发起者的系统 ID。

Body​

请参考 嵌入代码对内容进行加密，并在正文前添加消息类型指示符0025。

字段名是否必需类型长度描述示例
msgVer是String8版本数字"1.0"
billerType是String2付款类型"KP" - KPOS
callerDeviceType是String2呼叫设备类型."KP" - KPOS
callerDeviceVer是String8呼叫设备的应用版本数字。"1"
sequenceNo是String16在日历日内系统中唯一的运行消息序列数字，每天从 1 重新开始。"202409288868"
mrn是String40由 POS 系统分配的唯一参考数字，用于识别原始支付交易。"8e8c6e61-f9e4-40f0-a4a5-9e561579c901"
resultCode是String5结果代码"00000"
authIdResp条件的String16仅用于已批准交易的发卡行/银行授权码。消费者应将此代码作为已批准支付交易的参考。"484684"
paymentScheme条件的String2交易的支付方案。"AF" - 蚂蚁金融（支付宝）
"JC" - JCB
"MC" - 万事达卡
"PN" - Paynet（DuitNow）
"UP" - 银联（前称 CUP）
"VS" - Visa
maskedPAN条件的String4返回的掩码 PAN"443322XXX1234"
htr条件的String20主机交易参考
paymentMethod条件的Number2客户选择的最终支付方式，以完成付款。"00" - KPOS 将显示所有可用的支付方式，客户可以选择他们的首选方式进行支付。
"01" - 卡支付
"04" - Duitnow QR 支付（商户呈现）
"08" - Alipay+ QR 支付（商户呈现）
advMsg可选String1000来自 KPOS 的建议消息。"..."
paymentType条件的String3指定付款交易的类型，例如销售、预授权或销售完成。"STX" - 销售交易
mid是String15商户 ID"100000"
tid是String8终端 ID"2000200"
currency是Number3此交易的 ISO 4217 数字货币代码。"458"
amount是Number18金额，交易。
支持货币的购买交易金额。		"1000"
visDetails条件的ObjectVIS 交易的分期付款信息
receiptInfo条件的Object用于生成收据的附加信息。

注： 当 resultCode = "00000" 且 isPaymentReq = "Y" 时返回。
invoice条件的Object用于向 LHDN 提交的发票对象，以用于电子发票。

注： 当 billerType 为 "KP"（KPOS）且 callerDeviceType 为 "03"（自助服务亭）时返回。
Object: visDetails
字段名是否必需类型长度描述示例
numOfInstalment是Integer按指定频率分期付款的总期数。"10"
instalmentFrequency是String32付款频率。"WEEKLY" - 每周付款一次
"BIWEEKLY" - 每两周付款一次
"MONTHLY" - 每月付款一次
"BIMONTHLY" - 每两个月付款一次
instalmentAmount是Number18按指定频率应付的付款金额。"1000"
mdrFee是Number18此 VIS 交易的适用费用。"100"
Object: receiptInfo
字段名是否必需类型长度描述示例
acqCode是String20收单行代码。

注： 默认值为 FINEXUS。		"FINEXUS"
acqMid是String50商户 ID（用于支付处理）。"XXXXXXXXXXX3169"
acqTid是String30收单行终端 ID。"XXXX3992"
stan是Integer终端生成的系统跟踪审计号，用于标识交易。"000125"
rrn是String12收单行生成的检索参考号，用于标识交易。"617683000125"
authIdResp是String6仅用于已批准交易的发卡行/银行授权码。消费者应将此代码作为已批准支付交易的参考。"11XXXX"
aid条件的String32用于识别卡支付应用的应用标识符。

注： 当 paymentScheme 为 JC、MC、MD、UP 或 VS 时返回。		"A000000004XXXX"
appLabel条件的String64用于识别卡支付应用的应用标签。

注： 当 paymentScheme 为 JC、MC、MD、UP 或 VS 时返回。		"Debit Mastercard"
arqc条件的String32卡为特定交易生成的授权请求密文。

注： 当 paymentScheme 为 JC、MC、MD、UP 或 VS 时返回。		"45DA8D7588XXXXXX"
Object: invoice
字段名是否必需类型长度描述示例
invNo是String22发票号码。

注意： 对于新发票提交请求，此字段应包含新发票号码。
对于取消或退款请求，此字段应包含退款或贷项通知单的新发票号码。		"2024070712121200000001"
oriInvNo条件的String22原始发票号码。

注意： 对于取消或退款请求，此字段为必填项，以便 KPOS 将请求与正确的原始交易关联。		"2024070712121200000001"
invDt是Number8发票日期。

注意： 格式：yyyymmdd		"20240707"
invTm是Number6发票时间。

注意： 格式：hhmmss		"121212"
invCur是Number3此交易的 ISO 4217 数字货币代码。

注意： 仅支持货币代码 458		"458"
taxCur是Number3税务货币代码。

注意： 仅支持货币代码 458		"458"
billFreq可选String2计费频率代码。"01" - 每日
"02" - 每周
"03" - 每两周
"04" - 每月
"05" - 每两月
"06" - 每季度
"07" - 每半年
"08" - 每年
"09" - 其他/不适用
billStartDt条件的String8计费开始日期。

注意： 格式：yyyymmdd
当 billFreq 不为 09 时为必填项		"20240701"
billEndDt条件的String8计费结束日期。

注意： 格式：yyyymmdd
当 billFreq 不为 09 时为必填项		"20240731"
totalNet是Number净额合计。

注意： 为 item.totalExclTax 之和		"27800"
totalDisc可选Number折扣总额。

注意： 为 addAllowCharge.allowChargeAmt 之和		"100"
totalFeeCharge可选Number费用/收费总额。

注意： 为 addAllowCharge.allowChargeAmt 之和		"100"
totalExclTax是Number不含税总额。

注意： totalExclTax = totalNet – totalDisc + totalFeeCharge		"27800"
totalTax是Number税额合计。

注意： 为 item.taxAmt 之和		"0"
totalInclTax是Number含税总额。

注意： totalInclTax = totalExclTax + totalTax		"27800"
pmtMode可选Number付款方式。"01" - 现金
"02" - 支票
"03" - 银行转账
"04" - 信用卡
"05" - 借记卡
"06" - 电子钱包/数字钱包
"07" - 数字银行
"08" - 其他
supplierAcctNo可选String150供应商账号。"SUPPLIER-ACC-001"
prePmtAmt可选Number预付款金额。"100"
prePmtDt可选Number8预付款日期。

注意： 格式：yyyyMMdd		"20240630"
prePmtTm可选Number6预付款时间。

注意： 格式：hhmmss		"120000"
prePmtRefNo可选String150预付款参考号。"PREPMT-REF-001"
roundAmt可选Number舍入金额。

注意： 可为负值。
示例：若为负 MYR 0.10，则值为 -10
若为正 MYR 0.10，则值为 +10		"-10"
totalPayable是Number应付总额。

注意： totalPayable = totalInclTax-prePmtAmt+roundAmt		"27800"
billRefNo可选String150账单参考号。"BILL-REF-001"
items是Array构成发票的各个发票项目。
addAllowCharge可选Array附加津贴/费用。
shippingRecipient可选Object收货人。
denyIndividualEInvoice可选String1指示是否阻止客户请求个人电子发票。

注意： 可能值：
"Y" - 阻止客户请求个人发票；客户可通过 FIDU 网页/应用查看发票。
"N" - 允许客户请求个人发票。
如果此字段不存在，默认值为 N。		"N"
eSignature条件的String512电子签名。

注意： 详情请参阅 FINEXUS FIDU QR 规范。
提交发票且 denyIndividualEInvoice 不存在或为 'N' 时此字段为必填项
不适用于 getDocument 响应		"AbCDefghijklmnop"
pinCode条件的Number6用于保护发票不被未经授权人员认领的 6 位 PIN 码。

注意： 详情请参阅 FINEXUS FIDU QR 规范。
提交发票且 denyIndividualEInvoice 不存在或为 'N' 时此字段为必填项
不适用于 getDocument 响应		"000000"
Object: invoice item
字段名是否必需类型长度描述示例
oriInvNo条件的String22原始发票号码。

注意： 取消或退款请求时为必填项。		"2024070712121200000001"
classCde是String3分类代码。

注意： 详情请参阅 附录 6。		"038" - 体育设备、体育设施租赁/入场费或体育比赛注册
desc是String300产品/服务描述。"Li-Ning Wind Lite"
uom可选String3计量单位。"MTR" - 米
"EA" - 件
"H87" - 个
"KGM" - 千克
"LTR" - 升
unitPrice是Number单价。"27800"
qty可选String31数量。

注意： 允许值：数字和 "."		"1"
subtotal是Number小计。

注意： subtotal = unitPrice*qty		"27800"
discRate可选Number折扣率。

注意： 折扣率百分比（满分 100）		"10"
discAmt条件的Number折扣金额。

注意： 当 discRate 不为空时为必填项		"100"
feeRate可选Number费用/收费率。"5"
feeAmt条件的Number费用/收费金额。

注意： 当 feeRate 不为空时为必填项		"100"
totalExclTax是Number不含税总额。

注意： totalExclTax = subtotal-discAmt+feeAmt		"27800"
taxTyp是String2税种。"01" - 销售税
"02" - 服务税
"03" - 旅游税
"04" - 高价值商品税
"05" - 低价值商品销售税
"06" - 不适用
taxRate条件的Number税率。

注意： 当 taxTyp 不为 06 时为必填项		"6"
taxExemptInd可选String1免税指示符。

注意： 可能值：
"Y" – 是
"N" – 否 [默认]		"N"
taxExemptDtl条件的String300免税详情。

注意： 当 taxExemptInd=Y 时为必填项		"免税详情"
taxExemptAmt条件的Number免税金额。

注意： 当 taxExemptInd=Y 时为必填项		"100"
taxAmt条件的Number税额。

注意： 当 taxTyp 不为 06 时为必填项		"100"
totalInclTax是Number含税总额。"27800"
prodTariffCde可选String12产品关税代码。"TARIFF-001"
oriCountry可选String3原产国。"MYS" - 马来西亚
"SGP" - 新加坡
originSystemType可选String2来源系统类型。"01"
originSystem可选String50来源系统。"POS"
originModule可选String50来源模块。"SALES"
originBranch可选String50来源分支机构。"HQ"
originDept可选String50来源部门。"RETAIL"
originGLAccNo可选String20来源总账账号。"4000-001"
originGLType可选String1来源总账类型。"R"
originCustNo可选String20来源客户编号。"CUST-001"
originAcctNo可选String20来源账户编号。"ACCT-001"
originProdTyp可选String20来源产品类型。"RETAIL"
originTrxCde可选String20来源交易代码。"SALE"
givenItemId条件的String64商户分配的项目标识符。

注意： 如果在 KBIZ 中配置了菜单项，则为必填项。		"ITEM-038-001"
Object: allowance charge
字段名是否必需类型长度描述示例
allowChargeTyp是String1津贴/费用类型。"C" - 费用/收费
"D" - 折扣
allowChargeDesc是String100津贴/费用描述。"配送费"
allowChargeAmt条件的Number津贴/费用金额。"100"
Object: shipping recipient
字段名是否必需类型长度描述示例
name可选String300收货人姓名。"John Doe"
addr1是String150收件人地址 1。"Lot 66"
addr2可选String150收件人地址 2。"Bangunan Merdeka"
addr3可选String150收件人地址 3。"Persiaran Jaya"
state是String2收件人州属。

注意： 详情请参阅 附录 7。		"14" - 吉隆坡联邦直辖区
city是String50收件人城市。"Kuala Lumpur"
postcode可选String50收件人邮政编码。"50480"
country是String3收件人国家。

注意： 仅接受值：MYS		"MYS"
tin可选String16LHDN 系统分配的收货人 TIN。"C12345678900"
idType可选String8NRIC、护照号码、商业注册号、军人证号。

注意： 可能值：
- NRIC
- PASSPORT
- BRN
- ARMY		"NRIC"
idValue可选String64与 idType 关联的 ID 值。"200228105338"

示例请求和响应主体​

从主体中移除消息类型指示符 0025 并解密内容.

解密之前
0025eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsImtpZCI6ImU4NmQ0Y2ZiLTFkNzMtNDJkNi05MGVlLWRlNWJlNjcwMjVlOSIsIngiOiI0UmxIeDAzX3ZlTURWaGFaTl91TVppZ2YzV1dPWGlveG52Zy1rRXhyMzFrIiwieSI6ImcyU1VqNkJnVHdYakxWYWlTRnVobGtSWklrMndaWlNaMWJEWG1DSTZSVXcifSwia2lkIjoiMTIzIiwiZW5jIjoiQTI1NkNCQy1IUzUxMiIsImFsZyI6ImRpciJ9..UIzHIjrFX8fPX91SEUzZpA.9hmtgLHx_UZjYTwduAtdruZB60QPRPjvczVeJwSI7tomXmEU720zuokvMdf9VxQqHOh2PHvtTtqW8OZQuIqYyDmss06ii-fy73a897AJv2KXPARY6DduoiLSJwDCJKhBiJlnZkAMyRZdB5xGzJwXL21QaXbO86EF6_d9qzrOhQvrNlfkTOBQYnv5Mhnnetda0_zm59HRMW2mg-rEOGj1W0Q4U0I8ZZrXQSxO3MnalxuzWQ4oTU2uHZrFnsyL93PeKiG_RmIszQGXqG0bN8WsoJfL0BTd20rnxldLQcSZYNdxGJw0EBGwlSp7DTpcmP1kzd1v2PzLGISZiPa9zadcVuLaODBZQ5GdHoPgIi76pTRwDJrv1CuD8ugfuuu_L5DxFIErnqs5cTONqxhCQ23ZeCSbnuDJDJju9yyr2wYoFFKQQciZmPddPgi2phew31DRjju4y4Ab6H7Vv01gqk6h2b9clR7v54wZSvR0CVROLZj79nKM1eLDhEo8JEv6T5APb2EHMTaU-sIlT-XqENbwV-A5HSEuEdvU7K3fsgioU5qJWwk9SS1WWmyqHnvCK1Rl5azJcKbfyN07a7znZD66IAoSUoCHjsqmFC4bd6ckdLA.Q3Ys35PhzHsnNnlJQ3rzwR-RsfEmYeDxXDsw9h97Azo
移除消息类型指示符并解密后
{
    "msgVer": "1.0",
    "billerType": "KP",
    "callerDeviceType": "KP",
    "callerDeviceVer": "1",
    "sequenceNo": "2022091511262185",
    "mrn": "8e8c6e61-f9e4-40f0-a4a5-9e561579c901",
    "resultCode": "000000",
    "authIdResp": "484684",
    "paymentScheme": "VS",
    "maskedPAN": "443322XXX1234",
    "htr": "",
    "paymentMethod": "04",
    "paymentType": "STX",
    "mid": "000010000012XXX",
    "tid": "2000XXX",
    "currency": "458",
    "amount": "27800"
}

示例消息​

POST 请求
curl -X POST "https://xxx/xxx/paymentNotification" \
 -H "Accept: application/json" \
 -H "Content-Type: text/plain" \
 -H "Signature: ..." \
 -H "sourceSystem: ..." \
 -d '0025eyJlcGsiOnsia3R5IjoiRUMiLCJ...'

© 2026 Finexus Group。版权所有。