Appendix
Appendix A: Error Code#
| Type | Response code | Message |
|---|---|---|
| Success | 000 | Success |
| Authentication | A01 | Invalid API Key. |
| A02 | API Key expired, you will be redirected to login page. | |
| Error | E01 | Database error. UI: System is temporarily unavailable (E01) |
| E02 | Connection error. UI: System is temporarily unavailable (E02) | |
| E03 | Invalid date/time format | |
| E04 | Missing mandatory field | |
| E05 | System error. UI: System is temporarily unavailable (E06) | |
| E06 | Email service error. UI: System is temporarily unavailable (E07) | |
| E07 | Data not found | |
| E08 | Please input number only | |
| E09 | Checksum Failed | |
| E10 | Invalid Request | |
| E11 | MAID configuration is invalid | |
| E12 | Invalid QR code type | |
| Register | R01 | Mobile number not found. |
| R02 | User account is disabled. | |
| R03 | User need to change passcode | |
| R04 | Email address not found | |
| R05 | Email is already registered | |
| QR Code | Q01 | QR code is expired. |
| Q02 | QR code format is incorrect. | |
| Q03 | QR code is already existed. | |
| Q04 | QR code is not existed. | |
| Q05 | Merchant ID is not existed. | |
| Q06 | Terminal ID is not existed. | |
| Q07 | Invalid amount. | |
| Q08 | QRCodeType is not eligible to generate. | |
| Q09 | Merchant is disabled. | |
| Q10 | Terminal is disabled. | |
| Q11 | Amount is required. | |
| Q12 | Duplicate QR. | |
| Transaction | T01 | Invalid transaction ID. |
| T02 | Transaction is not eligible for full refund. | |
| T03 | Transaction is not eligible for a partial refund. | |
| T04 | Invalid refund amount. | |
| T05 | Invalid refund transaction ID. | |
| T06 | Transaction not found. | |
| T07 | Refund must be made on the same day as transaction. | |
| T10 | Invalid refund reference ID | |
| T11 | Partial void is not supported | |
| Notification | N99 | System error |
| N01 | Invalid transaction | |
| N02 | Per transaction maximum amount limit reached | |
| N03 | Merchant monthly transaction limit reached | |
| N04 | No permission for the channel | |
| N05 | QR code is inactive | |
| N06 | QR code is expired | |
| N07 | Duplicate QR | |
| N08 | Duplicate invoice | |
| N09 | Invalid amount | |
| N10 | Invalid MAID | |
| N11 | Merchant daily transaction limit reached |
Appendix B: QR CODE MESSAGE FORMAT#
Merchant – Presented QR Code format and content used in the application here are in accordance with EMVCo QRCPS, see Ref. 1. Additional format, deviation format or specific contents of QR Code for other channels should be defined under this appendix chapter.
B.1: MASTERCARD#
This section describes the requirements, and specific contents of QR code for MASTER CARD QR code.
Requirements
- CRC - The Receiving Institution must correctly generate an ISO/IEC 3309 compliant 4-character value derived from the all the Data Element values in the Data String i.e. the Cyclic Redundancy Checksum (CRC) denoted by id “63”. Data object “63” must be the last-placed data object in the QR Code.
- Mastercard Merchant ID - Denoted by id “04”. This data contains the ID(s) by which the Merchant may be identified and will bear the format of a standard 16-digit Mastercard PAN. In this case, only the first 15 digits will appear in the Data String and the OI must derive the final check digit based on the Modulus 10 / Luhn formula, and then populate the same into the Payment Transaction.
- MasterCard Merchant Assigned Identifier (MAID) – Where a MAID is applicable for a merchant, the RI must populate this MAID value in the merchant’s QR code, anywhere in the dynamically allocable id “26” – “51”, with sub id “01” immediately after the Mastercard AID of A0000000041010 with sub id “00”. Please refer to Table 4.
- Payment Facilitator Identifier (PF ID) – This is a unique identifier created and assigned to a payment facilitator (“PF”) acquiring merchants on behalf of a licensed Mastercard Receiving Institution. Where the merchant has been acquired by the PF, the merchant’s QR Code must be populated with the corresponding PF ID value anywhere in the dynamically allocable tags “26” – “51”, with sub id “02” immediately after the MAID with sub id “01” and Mastercard AID of A0000000041010 with sub id “00”. Please refer to Table 4.
- Merchant Name in a language other than English - Should a merchant have merchant information in an alternate language, RI can include this information on Merchant Information – Language Template with ID “62”. The sub id “00” is used for storing 2 alphabetical characters that represents Language Preference; the sub id “01” is used for storing Merchant Name in an alternate language; and the sub id “02” is used for storing Merchant City in an alternate language. Please refer to Table 5.
Table 4: Data Object for Merchant Account Information Template (Tag No "26" to"51") defined by Mastercard
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | Globally Unique Identifier | ans | up to "32" | M |
| 01 | Mastercard Assigned Merchant Identifier (MAID) | ans | up to “6” | O |
| 02 | Payment Facilitator ID | ans | up to “11” | O |
Remarks: Where applicable, MAID value will be stored in Tag No 51.
Table 5: Merchant Information Language Template with Tag No "64"
| Sub Tag No | Field Name | Format | Length |
|---|---|---|---|
| 00 | Language Preference | ans | "02" |
| 01 | Merchant Name – Alternate Language | S | up to "26" |
| 02 | Merchant City – Alternate Language | S | up to "15" |
| 03-99 | RFU for EMVCo | S | up to "99" |
B.2: PROMPTPAY#
This section describes the additional format, deviation format and specific contents of QR code for PromptPay. The PromptPay QR code will be implemented in accordance with Thai QR Code - Guide Line V.1.9 and Thai QR Code specification v1.31.
Table: PromptPay message specification deviation from the EMVCo standard
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 01 | Point of Initiation Method | N | “02” | M for PromptPay |
| 52 | Merchant Category Code | N | “04” | O for PromptPay |
| 55 | Tip or convenience indicator | N | "02" | N/A for PromptPay |
| 56 | Value of convenience fee fixed | ans, limited to numeric and the "." symbol | Up to “13” | N/A for PromptPay |
| 57 | Value of convenience fee pecentage | ans, limited to numeric and the "." symbol | Up to “05” | N/A for PromptPay |
| 59 | Merchant Name | ans | Up to “25” | M for card scheme, C for PromptPay |
| 60 | Merchant City | ans | Up to “15” | M for card scheme,O for PromptPay |
| 62 | Additional Data Field Template | S | Up to “99” | O |
| 62 (sub-tag 07) | Terminal Label | ans | Up to “25” | O for card scheme,C for PromptPay |
Table: Merchant Identifier for PromptPay credit transfer template with Tag No "29"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | AID | ans | "16" | M |
| 01 | Mobile Number | N | "13" | One of them is mandatory |
| 02 | National ID or Tax ID | N | "13" | One of them is mandatory |
| 03 | E-Wallet ID | N | "15" | One of them is mandatory |
| 04 | Bank Account | N | Up to "43" | One of them is mandatory |
| 05 | OTA | N | "10" | C |
Table: Merchant Identifier for PromptPay Bill Payment template with Tag No "30"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | ID | ans | “16” | M |
| 01 | Biller ID | N | “15” | M |
| 02 | Reference 1 | ans | Up to “20” | M |
| 03 | Reference 2 | ans | Up to “20” | O |
Table: Merchant Identifier for Payment Innovation (API) template with Tag No "31"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | AID | ans | “16” | M |
| 01 | Acquirer ID | N | “03” | M |
| 02-99 | Acquirer specific | ans | O |
Table: Merchant Identifier for Payment Innovation (Standard API) template with Tag No "31"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | AID | ans | “16” | M |
| 01 | API ID | N | “03” | M |
| 02 | Sending Bank ID | N | “03” | M |
| 03 | Transaction Ref | ans | “25” | M |
Table: Merchant Account Information (By Master Card) template with Tag No "51"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | Globally Unique Identifier | ans | up to "32" | M |
| 01 | Master Assigned Merchant identifier (MAID) | ans | up to “6” | O |
| 02 | Payment Facilitator ID | ans | up to “11” | O |
Table: TQRC VAT value template with Tag No "80"
| Sub Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | Seller Tax Branch ID | ans | "04" | M |
| 01 | Vat Rate | ans, limited to numeric and the "." symbol | up to "05" | O |
| 02 | Vat Amount | ans, limited to numeric and the "." symbol | up to "13" | M |
Remarks:
- The following optional fields - Reference 2 in Tag "30" and Terminal ID for bill payment in Tag "62" - if present must be sent to receiving bank.
- Referring to Tag No range from 02 – 51, one of these tag presence is mandatory, anything more than one is optional.
- See Thai QR Code - Guide Line V.1.9 and Thai QR Code specification v1.31 for further PromptPay QR implementation guideline.
B.3: GIP#
This section describes the additional format, deviation format and specific contents of QR code for GIP wallet channel. GIP wallet will reserve following tag number of QR Code message which describe in the table below to store its additional and specific contents.
Table: Merchant Identifier for GIP with Tag No "26"
| Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 26 | Merchant Identifier - GIP | ans | “16” | M |
B.4: UNIONPAY#
This section describes the additional format, deviation format and specific contents of QR code for UnionPay channel. UnionPay will reserve following tag number of QR Code message which describe in the table below to store its additional and specific contents.
Table: Merchant Identifier for UIP with Tag No "15" and “16”
| Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 15 | Merchant Identifier - UPI | ans | up to “99” | M |
| Acquirer IIN | ans | 8 | ||
| Forwarding IIN | ans | 8 | ||
| Merchant ID | ans | 15 | ||
| 16 | Merchant Identifier - UPI | ans | up to “99” | O |
Table: UnionPay message specification and specific remarks on original fields
| Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 52 | Merchant Category Code | N | “04” | M |
| 62 | Additional Data Field Template | S | Up to “99” | O |
| 62 (sub-tag 05) | Reference Label | ans | Up to “25” | C |
B.5: PAYNOW#
This section describes the additional format, deviation format and specific contents of QR code for Singapore PayNow. The PayNow QR code will be implemented in accordance with PayNow-QR-Specifications-ver1.6 and SGQR Specifications v1.7.
Table: Merchant Account Information (PayNow) with floating ID "26" (SGQR adopts a floating ID methodology)
| Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 00 | Globally Unique Identifier | N | “09” | M |
| 01 | Proxy type | N | “01” | M |
| 02 | Proxy Value | ans | Up to “16” | M |
| 03 | Editable Transaction amount indicator | N | “03” | O |
| 04 | QR Expiry Date | N | “08” | O |
| 05 | Merchant Reference Number (For static QR generation) | ans | Up to “25” | O |
B.6: JCB#
This section describes the additional format, deviation format and specific contents of QR code for JCB channel. JCB will reserve following tag number of QR Code message which describe in the table below to store its additional and specific contents.
Table: Merchant Identifier for JCB with Tag No "13" and “14”
| Tag No | Field Name | Format | Length | Mandatory |
|---|---|---|---|---|
| 13 | Merchant Account Information | ans | up to “99” | M |
| 14 | RFU for JCBI | ans | up to “99” | - |
Merchant PAN: Acquirers must generate a Merchant PAN for each merchant by concatenating its AIN with a unique 7-digit number, followed by a Check Digit. Example:
Merchant PAN: 3158 0000 0000 012x
Acquirer Identification Number: 31580000 (1st -8th digit)
Unique number for each Merchant: 0000012 (9th-15th digit)
Check Digit: x (16th digit)
Appendix C: REFERENCE DATA#
C.1: CHANNELS#
This section describes a list of channel and QR type which support by the system.
| Channel Name | Channel Code | QR Type |
|---|---|---|
| MasterCard | MTC | EM |
| VISA | VSA | EM |
| UnionPay | UPI | EM |
| UnionPay Online | UPO | EM |
| JCB | JCB | EM |
| PromptPay | TQR | PP |
| EMVCo+PromptPay | - | PE |
| AMEX | AMX | - |
| Diners | DIN | - |
| WCT | - | |
| AliPay | ALI | - |
| LINE | LNE | - |
| Global Issuing Project | GIP | GI |
| PayNow | PAN | PN |
| AirPay | AIR | AP |
| GrabPay | GRB | GR |
| CB Pay | CBP | CB |
| KBZ Pay | KBZ | KZ |
| ShopeePay | SHP | SP |
| GCash | GCH | GC |
| Mandalay Smart Pay | MSP | MP |
C.2: TRANSACTION STATUS#
| Status Code | Description |
|---|---|
| S | Settled |
| C | Canceled |
| F | Failed |
| SP | Settle Pending |
| RC | Refund Canceled |
| RS | Refund Settled |
| RF | Refund Failed |
C.3: REFUND REQUEST STATUS#
| Status Code | Description |
|---|---|
| RC | Refund Canceled |
| RS | Refund Settled |
| RF | Refund Failed |