Notification Parameters

Method POST

URL

https://xxx/xxx/paymentNotification

Request Parameters

Header

Field Name	Required	Type	Description
Signature	Yes	String	Contains the signature value of the message. The message originator is responsible for generating the signature, while the message receiver must verify it to ensure the integrity, authenticity, and non-repudiation of the message . Please refer to Appendix 1.
sourceSystem	Yes	String	The system ID of the message originator.

Body

Please refer to Embed Code to encrypt the content and prepend the Message Type Indicator 0025 to the body.

Field Name	Required	Type	Length	Description	Example
msgVer	Yes	String	8	Version number.	"1.0"
billerType	Yes	String	2	Type of payment.	"AM" - Automated Machine
callerDeviceType	Yes	String	2	Caller device type.	"17" - On-premises Car Parking System "18" - Cloud-based Car Parking System
callerDeviceVer	Yes	String	8	Application version number of the caller device.	"1"
sequenceNo	Yes	String	16	A running message sequence number which unique within system on a calendar day and shall restart from 1 every day.	"202409288868"
mrn	Yes	String	40	A unique reference number assigned by POS system to identify the original payment transaction.	"8e8c6e61-f9e4-40f0-a4a5-9e561579c901"
resultCode	Yes	String	5	Result code.	"00000"
authIdResp	Conditional	String	16	Authorization code from issuer/bank for approved transaction only. The consumer should use this code as the reference to the approved payment transaction.	"484684"
paymentScheme	Conditional	String	2	Payment scheme of the transaction.	"AF" - Ant Financial (Alipay) "JC" - JCB "MC" - MasterCard "PN" - Paynet (DuitNow) "UP" - UnionPay (fka CUP) "VS" - Visa
maskedPAN	Conditional	String	4	Returned Masked PAN.	"443322XXX1234"
htr	Conditional	String	20	Host Transaction Reference.
paymentMethod	Conditional	Number	2	The final payment method chosen by the customer to complete the payment.	"00" - KPOS will display all available payment method, the customer can then choose their preferred method to proceed. "01" - Card payment "04" - Duitnow QR payment (Merchant presented) "08" - Alipay+ QR payment (Merchant presented)
advMsg	No	String	1000	Advisory message from KPOS.	"..."
paymentType	Conditional	String	3	Specifies the type of payment transaction, such as sale, pre-authorization, or sales completion.	"STX" - Sale transaction
mid	Yes	String	15	Merchant ID	"100000"
tid	Yes	String	8	Terminal ID	"2000200"
currency	Yes	Number	3	ISO 4217 numeric currency code of this transaction.	"458"
amount	Yes	Number	18	Amount, Transaction. The purchase transaction amount in supported currency.	"1000"
visDetails	Conditional	Object		The instalment information for a VIS transaction
receiptInfo	Conditional	Object		Extra information used for receipt generation. Note: Present if resultCode = "00000" and isPaymentReq = "Y".
invoice	Conditional	Object		Invoice object to submit to LHDN for e-invoice purpose. Note: Present if billerType is "KP" (KPOS) and callerDeviceType is "03" (Self-service Kiosk).

Object: visDetails

Field Name	Required	Type	Length	Description	Example
numOfInstalment	Yes	Integer		The total number of payment breakdown over the specified frequency.	"10"
instalmentFrequency	Yes	String	32	The frequency of payment.	"WEEKLY" - Instalment payable every week "BIWEEKLY" - Instalment payable every two weeks. "MONTHLY" - Instalment payable every month "BIMONTHLY" - Instalment payable every two months
instalmentAmount	Yes	Number	18	The amount of payment payable on each specified frequency.	"1000"
mdrFee	Yes	Number	18	The applicable fees for this VIS transaction.	"100"

Object: receiptInfo

Field Name	Required	Type	Length	Description	Example
acqCode	Yes	String	20	Acquirer Code. Note: Default value: FINEXUS.	"FINEXUS"
acqMid	Yes	String	50	Merchant ID (used for payment processing purposes).	"XXXXXXXXXXX3169"
acqTid	Yes	String	30	Acquirer Terminal ID.	"XXXX3992"
stan	Yes	Integer		System Trace Audit Number generated by terminal to identify a transaction.	"000125"
rrn	Yes	String	12	Retrieval Reference Number generated by Acquirer to identify a transaction.	"617683000125"
authIdResp	Yes	String	6	Authorization code from issuer/bank for approved transaction only. The consumer should use this code as the reference to the approved payment transaction.	"11XXXX"
aid	Conditional	String	32	Application Identifier to identify payment application for cards. Note: Present if paymentScheme is JC, MC, MD, UP or VS.	"A000000004XXXX"
appLabel	Conditional	String	64	Application Label to identify payment application for cards. Note: Present if paymentScheme is JC, MC, MD, UP or VS.	"Debit Mastercard"
arqc	Conditional	String	32	Authorization Request Cryptogram generated by a card for a specific transaction. Note: Present if paymentScheme is JC, MC, MD, UP or VS.	"45DA8D7588XXXXXX"

Object: invoice

Field Name	Required	Type	Length	Description	Example
invNo	Yes	String	22	Invoice Number. Note: For new invoice submit requests, this field should contain the new invoice number. For cancel or refund requests, this field should contain the new invoice number for the refund or credit note.	"2024070712121200000001"
oriInvNo	Conditional	String	22	Original Invoice Number. Note: This field is mandatory for cancellation or refund requests, as it allows KPOS to associate the request with the correct original transaction.	"2024070712121200000001"
invDt	Yes	Number	8	Invoice Date. Note: Format: yyyymmdd	"20240707"
invTm	Yes	Number	6	Invoice Time. Note: Format: hhmmss	"121212"
invCur	Yes	Number	3	ISO 4217 numeric currency code of this transaction. Note: Only support currency code 458	"458"
taxCur	Yes	Number	3	Tax currency code. Note: Only support currency code 458	"458"
billFreq	No	String	2	Billing frequency code.	"01" - Daily "02" - Weekly "03" - Biweekly "04" - Monthly "05" - Bimonthly "06" - Quarterly "07" - Half-yearly "08" - Yearly "09" - Others / Not Applicable
billStartDt	Conditional	String	8	Billing start date. Note: Format: yyyymmdd Mandatory when billFreq is not 09	"20240701"
billEndDt	Conditional	String	8	Billing end date. Note: Format: yyyymmdd Mandatory when billFreq is not 09	"20240731"
totalNet	Yes	Number		Total Net Amount. Note: It is a sum of item.totalExclTax	"27800"
totalDisc	No	Number		Total discount amount. Note: It is a sum of addAllowCharge.allowChargeAmt	"100"
totalFeeCharge	No	Number		Total fee / charge amount. Note: It is sum of addAllowCharge.allowChargeAmt	"100"
totalExclTax	Yes	Number		Total excluding tax. Note: totalExclTax = totalNet – totalDisc + totalFeeCharge	"27800"
totalTax	Yes	Number		Total tax amount. Note: It is a sum of item.taxAmt	"0"
totalInclTax	Yes	Number		Total include tax amount. Note: totalInclTax = totalExclTax + totalTax	"27800"
pmtMode	No	Number		Payment mode.	"01" - Cash "02" - Cheque "03" - Bank Transfer "04" - Credit Card "05" - Debit Card "06" - e-Wallet / Digital Wallet "07" - Digital Bank "08" - Others
supplierAcctNo	No	String	150	Supplier account number.	"SUPPLIER-ACC-001"
prePmtAmt	No	Number		Pre payment amount.	"100"
prePmtDt	No	Number	8	Pre payment date. Note: Format: yyyyMMdd	"20240630"
prePmtTm	No	Number	6	Pre payment time. Note: Format: hhmmss	"120000"
prePmtRefNo	No	String	150	Pre payment reference number.	"PREPMT-REF-001"
roundAmt	No	Number		Rounding amount. Note: Can be negative value. Example: if negative MYR 0.10, the value is set at -10 if positive MYR 0.10, the value is set at +10	"-10"
totalPayable	Yes	Number		Total payable amount. Note: totalPayable = totalInclTax-prePmtAmt+roundAmt	"27800"
billRefNo	No	String	150	Bill reference number.	"BILL-REF-001"
items	Yes	Array		The individual invoice items that make up the invoice.
addAllowCharge	No	Array		Additional allowance / Charge.
shippingRecipient	No	Object		Shipping recipient.
denyIndividualEInvoice	No	String	1	Indicates whether the customer is prevented from requesting an individual e-invoice. Note: Possible Values: "Y" - Prevents the customer from requesting an individual invoice; the customer can view the invoice via the FIDU web/app. "N" - Allows the customer to request an individual invoice. If this field is not present, the default value is N.	"N"
eSignature	Conditional	String	512	E-signature. Note: Please refer to FINEXUS FIDU QR specification for detail. This field is required for submit invoice and denyIndividualEInvoice is not present or 'N' It is not applicable for getDocument response	"AbCDefghijklmnop"
pinCode	Conditional	Number	6	A 6 digit PIN code is used to protect the invoice from being claimed by an unauthorized person. Note: Please refer to FINEXUS FIDU QR specification for detail. This field is required for submit invoice and denyIndividualEInvoice is not present or 'N' It is not applicable for getDocument response	"000000"

Object: invoice item

Field Name	Required	Type	Length	Description	Example
oriInvNo	Conditional	String	22	Original Invoice Number. Note: It is mandatory for cancel or refund request.	"2024070712121200000001"
classCde	Yes	String	3	Classification code. Note: Please refer to Appendix 6 for details.	"038" - Sports equipment, rental / entry fees for sports facilities or registration in sports competition
desc	Yes	String	300	Product / service description.	"Li-Ning Wind Lite"
uom	No	String	3	Unit of measure.	"MTR" - metre "EA" - each "H87" - piece "KGM" - kilogram "LTR" - litre
unitPrice	Yes	Number		Unit price.	"27800"
qty	No	String	31	Quantity. Note: Allowable values: Numeric and "."	"1"
subtotal	Yes	Number		Subtotal. Note: subtotal = unitPrice*qty	"27800"
discRate	No	Number		Discount rate. Note: Discount rate percentage out of 100	"10"
discAmt	Conditional	Number		Discount amount. Note: Mandatory when discRate is not empty	"100"
feeRate	No	Number		Fee / Charge rate.	"5"
feeAmt	Conditional	Number		Fee / Charge amount. Note: Mandatory when feeRate is not empty	"100"
totalExclTax	Yes	Number		Total excluding tax. Note: totalExclTax = subtotal-discAmt+feeAmt	"27800"
taxTyp	Yes	String	2	Tax Type.	"01" - Sales Tax "02" - Service Tax "03" - Tourism Tax "04" - High-Value Goods Tax "05" - Sales Tax on Low Value Goods "06" - Not Applicable
taxRate	Conditional	Number		Tax rate. Note: Mandatory if taxTyp is not 06	"6"
taxExemptInd	No	String	1	Tax Exemption Indicator. Note: Possible values: "Y" – Yes "N" – No [Default]	"N"
taxExemptDtl	Conditional	String	300	Details of tax exemption. Note: Mandatory if taxExemptInd=Y	"Tax exemption details"
taxExemptAmt	Conditional	Number		Amount exempted from tax. Note: Mandatory if taxExemptInd=Y	"100"
taxAmt	Conditional	Number		Tax amount. Note: Mandatory if taxTyp is not 06	"100"
totalInclTax	Yes	Number		Total including tax.	"27800"
prodTariffCde	No	String	12	Product tariff code.	"TARIFF-001"
oriCountry	No	String	3	Country of origin.	"MYS" - Malaysia "SGP" - Singapore
originSystemType	No	String	2	Origin System Type.	"01"
originSystem	No	String	50	Origin system.	"POS"
originModule	No	String	50	Origin module.	"SALES"
originBranch	No	String	50	Origin branch.	"HQ"
originDept	No	String	50	Origin department.	"RETAIL"
originGLAccNo	No	String	20	Origin GL Account Number.	"4000-001"
originGLType	No	String	1	Origin GL Type.	"R"
originCustNo	No	String	20	Origin customer number.	"CUST-001"
originAcctNo	No	String	20	Origin account number.	"ACCT-001"
originProdTyp	No	String	20	Origin product type.	"RETAIL"
originTrxCde	No	String	20	Origin transaction code.	"SALE"
givenItemId	Conditional	String	64	Item identifier assigned by the merchant. Note: Mandatory if the menu item is configured in KBIZ.	"ITEM-038-001"

Object: allowance charge

Field Name	Required	Type	Length	Description	Example
allowChargeTyp	Yes	String	1	Allowance charge type.	"C" - Fee/Charge "D" - Discount
allowChargeDesc	Yes	String	100	Allowance charge description.	"Delivery fee"
allowChargeAmt	Conditional	Number		Allowance charge amount.	"100"

Object: shipping recipient

Field Name	Required	Type	Length	Description	Example
name	No	String	300	Shipping recipient name.	"John Doe"
addr1	Yes	String	150	Recipient address 1.	"Lot 66"
addr2	No	String	150	Recipient address 2.	"Bangunan Merdeka"
addr3	No	String	150	Recipient address 3.	"Persiaran Jaya"
state	Yes	String	2	Recipient state. Note: Please refer to Appendix 7 for details.	"14" - W.P. KUALA LUMPUR
city	Yes	String	50	Recipient city.	"Kuala Lumpur"
postcode	No	String	50	Recipient postal code.	"50480"
country	Yes	String	3	Recipient country. Note: Only accept value: MYS	"MYS"
tin	No	String	16	TIN of the shipping recipient assigned by the LHDN system.	"C12345678900"
idType	No	String	8	NRIC, Passport number, Business registration number, army number. Note: Possible values: - NRIC - PASSPORT - BRN - ARMY	"NRIC"
idValue	No	String	64	The ID value that associated with the idType.	"200228105338"

Response Parameters

Field Name	Required	Type	Length	Description	Example
sequenceNo	Yes	String	16	Sequence number echo from the request.	"1726817309256"
resultCode	Yes	String	5	Result code.	"00000"

Example Request and Response Body

Request

Remove the Message Type Indicator 0025 from the body and decrypt the content.

Before decryption

0025eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsImtpZCI6ImU4NmQ0Y2ZiLTFkNzMtNDJkNi05MGVlLWRlNWJlNjcwMjVlOSIsIngiOiI0UmxIeDAzX3ZlTURWaGFaTl91TVppZ2YzV1dPWGlveG52Zy1rRXhyMzFrIiwieSI6ImcyU1VqNkJnVHdYakxWYWlTRnVobGtSWklrMndaWlNaMWJEWG1DSTZSVXcifSwia2lkIjoiMTIzIiwiZW5jIjoiQTI1NkNCQy1IUzUxMiIsImFsZyI6ImRpciJ9..UIzHIjrFX8fPX91SEUzZpA.9hmtgLHx_UZjYTwduAtdruZB60QPRPjvczVeJwSI7tomXmEU720zuokvMdf9VxQqHOh2PHvtTtqW8OZQuIqYyDmss06ii-fy73a897AJv2KXPARY6DduoiLSJwDCJKhBiJlnZkAMyRZdB5xGzJwXL21QaXbO86EF6_d9qzrOhQvrNlfkTOBQYnv5Mhnnetda0_zm59HRMW2mg-rEOGj1W0Q4U0I8ZZrXQSxO3MnalxuzWQ4oTU2uHZrFnsyL93PeKiG_RmIszQGXqG0bN8WsoJfL0BTd20rnxldLQcSZYNdxGJw0EBGwlSp7DTpcmP1kzd1v2PzLGISZiPa9zadcVuLaODBZQ5GdHoPgIi76pTRwDJrv1CuD8ugfuuu_L5DxFIErnqs5cTONqxhCQ23ZeCSbnuDJDJju9yyr2wYoFFKQQciZmPddPgi2phew31DRjju4y4Ab6H7Vv01gqk6h2b9clR7v54wZSvR0CVROLZj79nKM1eLDhEo8JEv6T5APb2EHMTaU-sIlT-XqENbwV-A5HSEuEdvU7K3fsgioU5qJWwk9SS1WWmyqHnvCK1Rl5azJcKbfyN07a7znZD66IAoSUoCHjsqmFC4bd6ckdLA.Q3Ys35PhzHsnNnlJQ3rzwR-RsfEmYeDxXDsw9h97Azo

After remove Message Type Indicator and perform decryption

{
    "msgVer": "1.0",
    "billerType": "AM",
    "callerDeviceType": "17",
    "callerDeviceVer": "1",
    "sequenceNo": "2022091511262185",
    "mrn": "000000",
    "resultCode": "8e8c6e61-f9e4-40f0-a4a5-9e561579c901",
    "authIdResp": "484684",
    "paymentScheme": "AM",
    "maskedPAN": "443322XXX1234",
    "htr": "",
    "paymentMethod": "00",
    "paymentType": "STX",
    "mid": "000010000012XXX",
    "tid": "2000XXX",
    "currency": "458",
    "amount": "27800"
}

Response

Encrypt the content and prepend the Message Type Indicator 0026 to the body.

Before encryption

{
  "sequenceNo": "2022091511262185",
  "resultCode": "00000"
}

After encryption and add Message Type Indicator

0026eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsImtpZCI6ImI0YjIxMmM5LTIyNjMtNDAxYi1hZjdkLTMwOWI3MjRlOTEzOSIsIngiOiJvYmx1ZFdKRy1TTWJlakVqY1hlY3Q2dl9zY19ZZExyTzUtWEV2ZGFZQjdNIiwieSI6Il9MaFdTUDRrUUMwSkpWc09GMkJndWpfamc3dFZSMlRRcTctVExoUFZOeFUifSwia2lkIjoiOGM0MDFlYWMtYjM0OS00MDIyLWJhYTItZWNhMmQ3M2I4NTc5IiwiZW5jIjoiQTI1NkNCQy1IUzUxMiIsImFsZyI6ImRpciJ9..L2N0tzgQbvbbqjTa5XFCeA.TIgLgaNOwqFEchw3r0ls75zFL74mWBCJjuQFm7e7a2Ahk83m_xoS47g6m-Y7AewFcGFWBKbb4i0aGKW1moH70g.4JNcfZMyJqQKcadQIfxb224fqiM3MoUQ5ytA7lUQ4Bw

Example Message

Request

POST Request

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

Response

POST Response

0026eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsImtpZCI6ImI0YjIxMmM5LTIyNjMtNDAxYi1hZjdkLTMwOWI3MjRlOTEzOSIsIngiOiJvYmx1ZFdKRy1TTWJlakVqY1hlY3Q2dl9zY19ZZExyTzUtWEV2ZGFZQjdNIiwieSI6Il9MaFdTUDRrUUMwSkpWc09GMkJndWpfamc3dFZSMlRRcTctVExoUFZOeFUifSwia2lkIjoiOGM0MDFlYWMtYjM0OS00MDIyLWJhYTItZWNhMmQ3M2I4NTc5IiwiZW5jIjoiQTI1NkNCQy1IUzUxMiIsImFsZyI6ImRpciJ9..L2N0tzgQbvbbqjTa5XFCeA.TIgLgaNOwqFEchw3r0ls75zFL74mWBCJjuQFm7e7a2Ahk83m_xoS47g6m-Y7AewFcGFWBKbb4i0aGKW1moH70g.4JNcfZMyJqQKcadQIfxb224fqiM3MoUQ5ytA7lUQ4Bw