Napas - TechSpec For QR Payment - API - Bank - v0.8

API TECHNICAL SPECIFICATION
- FOR QR PAYMENT -
Version 0.8
11/2020
1
Table of contents
1 Introduction ............................................................................................................................. 5
1.1 Audience........................................................................................................................... 5
1.2 Scope ................................................................................................................................ 5
1.3 Support ............................................................................................................................. 5
1.4 Terms and abbreviation .................................................................................................... 5
1.5 How to use this document ................................................................................................ 6
2 Services and Use Cases ........................................................................................................... 7
2.1 Originating Institution calls API Lookup QR to Napas ................................................... 7
2.1.1 For domestic QR Code the flow lookup QR is required ........................................... 7
2.1.2 For cross border QR Code the flow lookup QR is required ..................................... 7
2.2 Customer uses application of Originating Institution to make payment at merchant of
Receiving Institution ................................................................................................................... 8
2.2.1 Domestic QR: the flow lookup QR is required ......................................................... 8
2.2.2 Cross border QR: the flow lookup QR is required ................................................... 9
2.3 Originating Institution calls API payment enquiry to get the status of payment
transaction when the response of the payment transaction status is timeout ............................ 10
2.3.1 For domestic............................................................................................................ 10
2.3.2 For cross border ...................................................................................................... 10
2.4 Receiving Institution calls API Void to cancel the original payment transaction ......... 11
2.4.1 Domestic ................................................................................................................. 11
2.4.2 Crossborder ............................................................................................................. 12
3 Technical Specification ......................................................................................................... 13
3.1 API General Contract ..................................................................................................... 13
3.1.1 General Protocol Description .................................................................................. 13
3.1.2 API Request ............................................................................................................ 14
3.1.3 API Response .......................................................................................................... 16
3.1.4 API Response Codes ............................................................................................... 20
3.2 Message Format for INCOMING Request .................................................................... 22
3.2.1 Account Services .................................................................................................... 22
3.2.2 QR Switch Services ................................................................................................ 25
3.3 Message Format for OUTGOING Request .................................................................... 50
3.3.1 Create Transaction Inquiry ..................................................................................... 50
3.3.2 Create Proxy Lookup Request ................................................................................ 53
2
3.3.3 Create Merchant Payment ....................................................................................... 57
3.3.1 Create Merchant Void Payment .............................................................................. 67
4 Appendix A – Data Protection............................................................................................... 76
4.1 Certificate Scheme Exchange......................................................................................... 76
4.1.1 Key/certificates are provided by NAPAS to Partners ............................................. 77
4.1.2 Key/certificates are provided by Partners to NAPAS ............................................. 77
4.2 Message Signature.......................................................................................................... 77
4.2.1 Client to NAPAS..................................................................................................... 78
4.2.2 NAPAS to Client..................................................................................................... 78
4.3 Content Encryption ........................................................................................................ 78
4.3.1 account.data.profile ................................................................................................. 78
5 Appendix B – JWE/JWS standard ......................................................................................... 80
5.1 JWE Details .................................................................................................................... 80
5.2 JWS Details .................................................................................................................... 80
6 Appendix C - Reconciliation File Format. ............................................................................ 82
6.1 Successful transaction file and processed transaction file in a session .......................... 82
6.1.1 Header line format (Header) ................................................................................... 82
6.1.2 Detail line format (Detail) ....................................................................................... 83
6.1.3 Trailer line format (Trailer) .................................................................................... 92
6.2 Detail line format (Detail) .............................................................................................. 93
6.2.1 Header line format (Header) ................................................................................... 94
6.2.2 Detail line format (Details) ..................................................................................... 94
6.2.3 Trailer line format (Trailer) .................................................................................. 102
3
Document Control
Version Updated date Updated by Reviewed by Description
0.1 18-Jun-2019 Le Van Lang Create techspec for payment intermediary to cover
all services, including:
- QR Switch
- Query Service
This document also includes both incoming and

outgoing message format.
0.1 11-Aug-2020 Le Thanh Tung Do Thi Ha Add techspec following service:
- Lookup service
- Inquery transaction (update)
- QRpayment
0.2 18-Aug-2020 Le Thanh Tung Do Thi Ha Add techspec following service:
- Void
0.3 13-Nov-2020 Le Thanh Tung Do Thi Ha 1. Add additional_info to (3.2.2):
- Lookup Response
- Payment request/response
- Void request/response
- Inquiry request/response
2. Change generation rule:
- header.reference-id – 3.2.2
- payment_reference – 3.1.3
3. Revision of field type of Amount as String
0.4 23-Apr-2021 Le Thanh Tung Do Thi Ha Revise lookup transaction applied for both
Domestic and Cross border transaction
0.5 18-May-2021 Bui Quang Minh Pham Xuan Loc Update ID 38 as Napas QRformat
0.6 22-Jun-2021 Bui Quang Minh Do Thi Ha Change interface message Inquery transaction
0.7 11-Aug-2021 Bui Quang Minh Do Thi Ha 1. Update format field message Inquery transaction
Pham Xuan Loc 2. Update format field condition for domestic QR:
- payment_reference: update for domestic QR
- order_info.store_label,
payment.end_to_end_reference : update from
Optional to Condition if QR has data
0.8 14-Oct-2021 Bui Quang Minh Do Thi Ha Update response code.
4
1 Introduction
NAPAS QRcode Switching service provides technical supplement service to connect, transfer,
transmit and handle electronic data for payment transaction between payment intermediaries and
banks by using QR Code.
The service allows customer to use mobile banking application to make payment transaction by
scanning QR Code/ e-wallet to pay at merchants
1.1 Audience
The audience of this document is Payment Intermediary connecting QRcode switching service.
1.2 Scope
This document describes the general API contract, interfaces, data format, request and responses
of transactions to be used for integration between Napas and Payment Intermediary.
1.3 Support
For any assistance or information pertaining to existing or new QRcode switching services, kindly
contact Napas Support.
1.4 Terms and abbreviation

Below table describes all terms and abbreviations using in this document:
STT Abbreviation Description

1 Originating Bank or Payment Intermediary provides payment application to
Institution customer, debit their accounts and create payment request as customer’s
need.
2 Receiving Bank or Payment Intermediary receives payment request, credit account
Institution merchant account
3 Issuing Bank The financial Institution that provides account or/and issues card to
customer.
4 Acquiring The financial Institution that provides account or/and processes card
Bank transaction.
5 Payment Entities that are granted license by the State Bank of Vietnam to
Intermediary provide Payment Intermediary services including electronic payment
portal, cash collection and payment services, electronic money transfer
services; and e-wallet services.
6 E-wallet E-wallet is a digital account provided by Payment Intermediary or
/Mobile issuing bank to make transaction including but not limited to cash-in,
wallet cash-out, electronic money transfer, make payment to merchant.
5
7 QRcode QRcode application is the mobile application provided by bank or bank
application intermediary to support payment transaction by QRcode at applicable
merchants.
1.5 How to use this document

All technical APIs described in this document based on technical specification and function of
QR Push payment
All API’s fields are described by their attributes:
- Field Name: Name of field as used to form the system call.

- Field Type: this field is numerical, alpha …
- Length: length of field value
- Request: request message to Napas
- Response: response message from Napas
- Description: Field detail description.
Field indicator:
- O: Optional – data element is optional

- M: Mandatory: specify whether data element is required
- C: Conditional – presenting this field if some conditions are met.
6
2 Services and Use Cases
2.1 Originating Institution calls API Lookup QR to Napas
Note: If the QR string contains the character set ‘5802VN’ then it is domestic QR Code and vice
versa the QR string contains other character set ‘5802VN’ then is is cross border QR Code.
2.1.1 For domestic QR Code the flow lookup QR is required
Step 1: Customer purchases a product and selects pay by QR Code that initial request to
Originating Institution
Step 2: Originating Institution creates and sends Lookup request to Napas
Step 3: Napas sends Lookup request to Receiving Institution
Step 4: Receiving Institution creates and sends lookup response to Napas
Step 7: Napas sends lookup response to Originating Institution
Step 8: Originating Institution shows information QR on the screen mobile application
2.1.2 For cross border QR Code the flow lookup QR is required

Originating Institution will check the QR string. If ID58 in the string QR has value other
character set ‘5802VN’ then Originating Institution will rout the lookup request to Napas.
7
Originating Institution
Step 2: Originating Institution creates and sends Lookup request to Napas
Step 3: Napas sends Lookup request to Foreign Payment Gateway
Step 4: Foreign Payment Gateway sends lookup request to Receiving Institution
Step 5: Receiving Institution creates and sends lookup response to Foreign Payment Gateway
Step 6: Foreign Payment Gateway sends lookup response to Napas
Step 7: Napas sends lookup response to Originating Institution
Step 8: Originating Institution shows information QR (plus exchange rate if it is cross border
QR) on the screen mobile application
2.2 Customer uses application of Originating Institution to make

payment at merchant of Receiving Institution
Note: Originating Institution may be Issuing bank or Payment Intermediary. Receiving

Institution may be Acquiring bank or Payment Intermediary
2.2.1 Domestic QR: the flow lookup QR is required
Originating Institution. Customer confirms payment on the mobile application
8
Step 2: Originating Institution debits customer’s account
Step 3: Originating Institution creates and sends payment request to Napas
Step 4: Napas sends payment request to Receiving Institution
Step 5: Receiving Institution credits merchant’s account
Step 6: Receiving Institution sends payment response to Napas
Step 7: Napas sends payment response to Originating Institution
Step 8: Originating Institution shows payment result for customer
2.2.2 Cross border QR: the flow lookup QR is required
Step 1: Customer confirms payment on the mobile application

Step 2: Originating Institution debits customer’s account
Step 3: Originating Institution creates and sends payment request to Napas
Step 4: Napas sends the payment request to Foreign Payment Gateway
Step 5: Foreign Payment Gateway sends the payment request to Receiving Institution
Step 6: Receiving Institution credits merchant’s account
Step 7: Receiving Institution sends the payment response to Foreign Payment Gateway
Step 8: Foreign Payment Gateway sends the payment response to Napas
Step 9: Napas sends the payment response to Originating Institution
Step 10: Originating Institution shows the payment result for customer on the mobile application
9
2.3 Originating Institution calls API payment enquiry to get the
status of payment transaction when the response of the
payment transaction status is timeout
2.3.1 For domestic
Step 1: Originating Institution creates and sends request payment enquiry to Napas.
Step 2: Napas sends request payment enquiry to Receiving Institution.
Step 3: Receiving Institution sends response payment enquiry to Napas.
Step 4: Napas sends response payment enquiry to Origination Institution.
2.3.2 For cross border
Step 1: Originating Institution creates and sends request payment enquiry to Napas.
Step 2: Napas sends request payment enquiry to Foreign Payment Gateway.
Step 3: Foreign Payment Gateway sends request payment enquiry to Receiving Institution.
Step 4: Receiving Institution creates and sends response payment enquiry to Foreign Payment
Gateway.
Step 5: Foreign Payment Gateway sends response payment enquiry to Napas.
Step 6: Napas sends response payment enquiry to Originating Institution.
10
2.4 Receiving Institution calls API Void to cancel the original
payment transaction
The cancellation must performed in the same session with the original payment transaction.
2.4.1 Domestic
From step 1 to step 8 see at session 2.2.1

Step 9: When the merchant want to cancel the original payment transaction, the merchant
performs send request cancellation to Receiving Institution (ACQ of original payment
transaction). Receiveing Institution (ACQ of original payment transaction) debits the merchant’s
account.
Step 10: Receiving Institution (ACQ of original payment transaction) creates and sends Void
request to Napas.
Step 11: Napas sends Void request to Originating Institution (ISS of original payment
transaction).
Step 12: Originating Institution (ISS of original payment transaction) credits the customer’s
account.
Step 13: Originating Institution (ISS of original payment transaction) creates and sends Void
response to Napas.
Step 14: Napas sends Void response to Receiving Institution (ACQ of original payment
transaction).
11
Note: Originating Institution and Receiving Institution inform their customers themselves
through their applications or their devices.
2.4.2 Crossborder
From step 1 to step 10 see at session 2.2.2

Step 11: When the merchant want to cancel the original payment transaction, the merchant
performs send request cancellation to Receiving Institution (ACQ of original payment
transaction). Receiveing Institution (ACQ of original payment transaction) debits the merchant’s
account.
Step 12: Receiving Institution (ACQ of original payment transaction) creates and sends Void
request to Foreign Payment Gateway.
Step 13: Foreign Payment Gateway sends Void request to Napas.
Step 14: Napas sends Void request to Originating Institution (ISS of original payment
transaction).
Step 15: Originating Institution (ISS of original payment transaction) credits the customer’s
account.
Step 16: Originating Institution (ISS of original payment transaction) creates and sends Void
response to Napas.
12
Step 17: Napas sends Void response to Foreign Payment Gateway.
Step 18: Foreign Payment Gateway sends Void response to Receiving Institution (ACQ of
original payment transaction).
Note: Originating Institution and Receiving Institution inform their customers themselves
through their applications or their devices.
3 Technical Specification
This section provide the detail technical specification for integrate between partners to Napas,
where the connecivity can be either client to Napas or vice-versa.
Napas’s APIs are based on JSON message format with JWE/JWS for securing confidential
information.
3.1 API General Contract

3.1.1 General Protocol Description
NAPAS APIs are published as RESTful Web Service on which the partner can interact with our
financial services via HTTP protocol and HTTP verbs.
URL {NAPAS_API_BASE_URL}/{sub_system}/{version}/{resource/operation}/{id}
Example:
https://api.napas.com.vn/qrsw/v1/partners/45e04108-a022-11e4-89d3-
123b93faecba/merchant/payment/680AA78674514866887322859D8CEC9A
Authentication Mutual SSL / Digital Signature
Transmission HTTPS
Messaging Restful-JSON
Security Method JWE/JWS (if applicable)
By default, NAPAS uses the same message format for both incoming request (where the client
calls NAPAS APIs) and also outgoing request (where NAPAS call partner APIs). For outgoing
request from NAPAS to partner, the APIs URL may be in different format with NAPAS APIs.
Any specific message format required by external partner will be supported as customization
during integration phase.
For security reason, all the sensitive data elements in API request and response messages are
protected by JWE/JWS security method. Service consumers and service provider should provide
each other the key set for using in encryption and signature verification.
Detail of key scheme exchange and data protection are described in Appendix A – Data
Protection.
13
Supported API
API Name Direction Domestic Cross border Description
Create Incoming/Outgoing Optional Optional Sent by Originating Institution
Transaction to Napas or sent by Napas to
Inquiry Receiving Institution
Create Proxy Incoming/Outgoing Optional Required Sent by Originating Institution
Lookup Request to Napas/ Sent by Napas to
Receiving Institution
Create Incoming/Outgoing Required Required Sent by Originating Institution
Merchant to Napas/ Sent by Napas to
Payment Receiving Institution
Create Incoming/Outgoing Optional Optional Sent by Receiving Institution of
Merchant Void original payment transaction to
Napas/ Sent by Napas to
Originating Institution of
payment transaction
3.1.2 API Request

(1) POST / PUT Method
For any POST method to create or PUT to update a resource to NAPAS Service APIs, below
format will be used in HTTP body in general:
14
The request message to NAPAS Service APIs must contain a header tag with the information
about service consumer. The header.requestor.id tag is required and will be provided to partner
by NAPAS during on-boarding process.
Field name Field type Length Mandatory Description

header Object R API request header data group
header.requestor Object R Service consumer data group.
header.requestor.id String R ID of registered service consumer in NAPAS system.
header.requestor.name String O Name of registered service consumer.
header.reference-id String R Reference id of request. This value should be generated and
maintained in service consumer system.
Assigned by sending bank or gateway to uniquely identify

a transaction. The format of this field define respectively by
each scheme.
Format:
MMDDHHMMSSxxxxxxFFFFFYDDDHHnnnnnn
Pos 1-10: 10 digits Date/Time with format (GMT+7)
MMDDHHMMSS
Pos 11-16: 6 digits System Trace Number
Pos 17-22: 6 chars sending gateway bic code
Pos 23-35: 12 chars Unique Id (YDDDHHnnnnnn)
header.timestamp Number O Timestamp of the request.
header.operation String R The formal operation name of the request. This value must
be matched with operation definition from NAPAS.
15
header.signature String O Signature of the request message, details of generating
signature are described in Appendix A – Data Protection,
part 3.1 Message Signature.
payload Object R API request payload data group. This can be any
business message.
(2) GET Method

For any GET/DELETE method to retrieve or delete a resource to NAPAS Service APIs, the
header element must be contained in HTTP header.
Request HTTP header custom fields:

Field name Field type Mandatory Description
The JSON string which represent the ‘header’ object
header String R
which described in section 2.1.2.(1)
3.1.3 API Response

The API response contains:
Part Description
HTTP status code HTTP status code indicating success or failure
Header HTTP header relevant to request.
HTTP body to contain resource representation on success, or Error
Body
representation on failure
16
The response HTTP body is constructed by 3 parts:
17
- header: The API response header data group. This part contains the general information
of response as well as a reference to requested message header.
- result: application specific error information data group.
- payload: contains the business message elements.

header Object R API request header data group
header.operation-id String R The id of processed operation
header.operation-name String O Name of processed operation
header.requested-by Object R Contains the original requested header data group
header.requested-by.requestor Object R Service consumer data group
ID of registered service consumer in NAPAS
header.requested-by.requestor.id String R
system
header.requested-by.requestor.name String O Name of registered service consumer
Reference id of request. This value should be

header.requested-by.reference-id String R generated and maintained in service consumer
system
header.requested-by.timestamp Number O Timestamp of the original request
The formal operation name of the request. This
header.requested-by.operation String R value must be matched with operation definition
from NAPAS.
header.requested-by.signature String O Signature of the original request.
header.timestamp Number O Timestamp of the response message
header.signature String O Signature of the response message
result Object R Operation result data group
Result reference id. This value can be used for
result.id String R
querying status detail api
result.code String O Application specific error code
result.message String O Application specific error message
result.description String O Error description. Optional
Error Severity. Optional
Must be one of:
FATAL – Error that causes system to crash,

resulting in data loss or corruption or system not
responsive.
ex) Out of Memory, Out of Disk. Alerts must be
generated immediately
result.severity String O ERROR – Error that might cause the data loss or
corruption or system not responsive, if not fixed
soon.
ex) Database connection error. Alerts must be
generated if issue persists for a given period.
Immediate action must be taken to fix.
WARNING – Error that might lead to severe error

if not fixed.
ex) ClassCastException
Fully qualified resource identifier for the error.
result.href String O
Optional
18
Contains the response business message object.
payload Object O
This can be any business message.
19
3.1.4 API Response Codes
The API result is determined by HTTP status code. Below table define the HTTP status codes to
indicate the response is success or failure:
HTTP Status Code Description
2xx Success
200 OK
201 Created. Normally use in create resource.
202 Accepted. Normally use in update resource
204 No Content
205 Reset Content
4xx Client Error
400 Bad request
401 Unauthorized
403 Forbidden
404 Not Found
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
412 Precondition Fail
415 Unsupported Media Type
5xx Server Error
500 Internal Server Error
501 Not Implemented
503 Service Not Available
For more detail of application specific errors, the HTTP body contains a result tag to represent
an application error detail resource.
Code Description
404.01 Refer to card issuer
404.03 Invalid Merchant
400.04 Pick-up
500.05 Unable To Process
406.07 Finished payment
406.08 The bill expired
406.09 The bill not exists
400.12 Invalid transaction
400.13 Invalid amount
400.14 Invalid Card number
404.15 No such Issuer
20
400.21 Card not initialized
400.25 Unable to locate original transaction
400.30 Message Format Error
400.34 Suspected Fraud
400.39 No credit account
400.41 Lost Card
400.43 Stolen Card
400.51 Insufficient Balance
400.53 No saving account
400.54 Expire Card
400.55 Incorrect PIN
400.57 Transaction not permitted to cardholder
406.58 Transaction not permitted to terminal
400.59 Suspected Fraud
400.61 Exceeds withdrawal amount limit
406.62 Restricted Card
401.63 Security Violation
400.64 Original Amount Incorrect
403.65 Exceed withdrawal frequency limit
408.68 Response received too late (time-out)
400.75 Allowable number of PIN tries exceeded
400.76 Invalid Account
401.84 validation error
401.85 No CVM Threshold exceeded, enter PIN
503.90 Cut-off is in progress
501.91 Issuer or switch is in operation
501.92 Financial Institution or intermediate network facility cannot be found for routing
400.94 Duplicate transaction
500.96 System malfunction
403.31 Exceed payment limit
500.1 System Error
408.2 Timeout
400.25 Invalid bank code
500.08 Error connecting to destination gateway
500.24 Can connect, error no response from destination gateway
400.02 QR format does not support
400.10 QR data missing/Currency not support
406.06 Payment not found
400.16 Exceeds the allowed number of times
400.37 Destination Bank/Switch does not support this service
400.38 Enquiry request is not the same session as the original payment transaction
21
3.2 Message Format for INCOMING Request
This section describe the business message format for all incoming requests from client to
Napas APIs. The object models in this section are used in payload part of request and response
message follow by API General Contract.
3.2.1 Account Services

NAPAS Account services provide the API to client to inquiry account information in detail
whether it is card PAN, bank account or token which was generated by a specific Tokenization
Service Provider (TSP). NAPAS Account services receive request from client and get account
information throught its payment network.
NAPAS_API_BASE_URL https://<host>:<port>/qrsw/v1/partners
Create Transaction Inquiry
This API is provided by NAPAS to Originating Institutions for querying the payment
transaction status in case of unclear failure or timeout. Napas will route the payment inquiry
request to corresponding receivers through its payment network.
The current support of this API only include Napas Ecommerce Payment System.
Operation URL {NAPAS_API_BASE_URL}/{partner_id}/merchant/transaction/inquiry
HTTP Method POST
Authentication Signature
Protocol REST-JSON
Security Method JWE/JWS
header.operation TRANSACTION_INQUIRY
Request Payload Fields detail

Field
Field name Length Mandatory Description
type
sender String 1..8 R Id of sending institution of inquiry transaction
receiver String 1..8 R Id of receiving institution of original transaction
id_message String 1..35 Id that identifies a message is unique.
For ITMX QR, you must follow the rules of ITMX:
ITMX Format:
MNYYYYMMDDHHmmssbbbnnnnnnnnnnnnnnnn
Pos. 01-01 - fixed value 'M'
R Pos. 02-02 - Node Identification (1 numeric
character)
Pos. 03-16 - System Date/Time in format
YYYYMMDDHHmmss (GMT+7)
Pos. 17-19 – sending bank code
Pos: 20 -35 - unique serial number (identical to the
number use in the BAH)
22
datetime String 1..25 Date and time of sending query transaction
R VD: 2019-03-25T10:32:24.634+07:00
type String 1..10 Valid value are:
QR_PUSH
CASHIN
R
CASHOUT
EFT
trace String 1..6 R System trace audit number of original transaction
txId String 1..35 TxId of the transaction that inquiry the state.
At the beginning of the organization issue the VN

call ESB, this value does not exist
O At the beginning of the ESB call request to ITMX,

this value should be included in the message
camt.005
The first ITMX call request camt.005 to ESB needs

this value
id_orig_payment String 1..35 The EndToEndId of the parent transaction needs to
R query the state. Unique id number to identify end to
end payment transactions.
orig_datetime String 1..25 R Date and time of the original payment transaction
orig_amount Number 1..12 R Amount of original payment transaction
orig_ccy String 1..3 R Currency of the original payment transaction
original_originating_institution String 1..8 The organization sending the original payment

R
transaction
original_receiving_institution String 1..8 Organization receiving the original payment
R
transaction
original_debtor_institution String 1..19 R Debit institution of the original transaction
debtor_account String The debit account number of the original
transaction. The PCIDSS standard should be
R followed if it is a card number.
Encrypted this information

original_creditor_institution String 1..19 R Credit organization of the original transaction
creditor_account String The credit account number of the original
Response HTTP Header

HTTP Header: HTTP/1.1 200 OK
Content-Type application/json
23
Location A complete URL to check the status of the request
Response Payload Fields detail

sender String 1..8 R Id of sending institution of inquiry
transaction
receiver String 1..8 R Id of receiving institution of original
transaction
id_message String 1..35 R Id that identifies a message is unique.
For ITMX QR, you must follow the rules of

ITMX:
ITMX Format:
MNYYYYMMDDHHmmssbbbnnnnnnnnn
nnnnnnn
Pos. 02-02 - Node Identification (1 numeric
character)
Pos: 20 -35 - unique serial number (identical
to the number use in the BAH)
datetime String 1..25 R The date and time of sending the query
transaction result response
VD: 2019-03-25T10:32:24.634+07:00
trace String 1..6 O System trace audit number of original
transaction
txId String 1..35 R TxId of the transaction that inquiry the state.
id_orig_payment String 1..35 O The EndToEndId of the parent transaction

needs to query the state. Unique id number
to identify end to end payment transactions.
orig_resp_datetime String 1..25 O Date and time of the original payment

transaction
transaction_code String 1..6 O Status Code of the original payment
transaction
description String 1..100 O Description for the status code of the
original transaction
error_code String 1..6 O Error code request payment enquiry
error_desc String 1..100 O Error description request payment enquiry
orig_amount Number 1..12 O Amount of original payment transaction
24
orig_ccy String 1..3 O Currency of the original payment
transaction
settle_date Date 1..25 O The settlement date of the original
transaction, if the original transaction is
settled
3.2.2 QR Switch Services

NAPAS QRcode Switching service provides technical supplement service to connect, transfer,
transmit and handle electronic data for payment transaction between payment intermediaries and
banks by using QR Code.
The service allows customer to use mobile banking application to make payment transaction by
scanning QR Code/ e-wallet to pay at merchants.
Domestic QR Code:
VNĐ
Ngân hàng
Khách hàng 1 Phát hành /
quét mã QR, Trung gian Ngân hàng Thanh toán / Trung
nhập PIN và thanh toán gian thanh toán gửi xác nhận
số tiền giao gửi xác nhận
5 thanh toán tới đại lý
dịch 8 thanh toán tới
khách hàng
Ngân hàng Thanh toán / Trung gian

NAPAS xác nhận thanh toán tới
thanh toán xác nhận thanh toán tới
Ngân hàng Phát hành / Trung gian
NAPAS
thanh toán
Ngân hàng Phát hành / 7 6

Trung gian thanh toán xác
thực trạng thái tài khoản
2
của khách hàng 3 4
Ngân hàng Phát hành / Ngân hàng Thanh toán /
Trung gian thanh toán Ngân hàng Phát hành / Trung gian NAPAS chuyển tiền tới Ngân hàng Trung gian thanh toán
thanh toán trừ tiền tài khoản của Thanh toán / Trung gian thanh
khách hàng và chuyển tiền tới toán
NAPAS
Section 1 – Domestic QRcode high level model

Cross border QR Code: Vietnam’s cutomer scan QR code at Merchant’s foreign store
25
Vietnam s customer scan QR Code at Merchant s foreign store
Vietnam s customer Foreign merchant QR

1
2 6
3 4 5
Foreign s Acquiring Bank

VietNam s Issusing Bank Foreign Gateway
VietNam s Settlement Bank Foreign s Settlement Bank
Transaction flow
Settlement flow
Section 2 – Vietnam’s cutomer scan QR code at Merchant’s foreign store high

level model
Cross border QR Code: Foreign’s cutomer scan QR code at Merchant’s VietNam store
Foreign s customer scan QR Code at Merchant s VietNam store
Foreign s customer Vietnam merchant QR

1
2 6
3 4 5
VietNam s Acquiring Bank

Foreign s Issusing Bank Foreign Gateway
Foreign s Settlement Bank VietNam s Settlement Bank
Transaction flow
Settlement flow
Section 2 – Foreign’s cutomer scan QR code at Merchant’s VietNam store high

level model
26
Following the QRcode switching model, Payment Intermediary or bank plays a role as Receiving
Institution or Originating Institution .
- Originating Institution: bank or Payment Intermediary provide payment application, debit

the account and send request payment as customer’s need.
- Receiving Institution: bank or Payment Intermediary gets the payment request, credit
merchant’s account.
QRcode Switching service technical specification document for Payment Intermediary describes
function, technical communication, data exchange between Napas and Payment Intermediary in
the context Payment Intermediary plays as Receiving Institution or Originating Institution.
This set of APIs is used for create the payment to merchant account, after fund has been
deducted from consumers at Originating Institution.
NAPAS_API_BASE_URL https://<host>:<port>/qrsw/v1/partners
(1) Create Proxy Lookup Request
This API is provided by NAPAS to Originating Institutions for QR Transformation for any
country including Vietnam. Napas will route the lookup request to corresponding receivers
through its payment network. The API proxy lookup will convert QR code string of any country
into a standard format that includes sufficient information that issuer bank can make cross border
payment.
The receiving Institution s can be either payment intermediaries or NAPAS’s member banks:
NAPAS will send an outbound API call to Payment Intermediary, follow current NAPAS API
general contract standard with payload message as described in 3.3.2 Create Proxy Lookup
Request.
Operation URL {NAPAS_API_BASE_URL}/{partner_id}/merchant/lookup
HTTP Method POST
Protocol REST-JSON
header.operation QRLOOKUP

Field
type
The Payment Reference is assigned by the Debtor Bank to
uniquely identify a single Credit Transfer within a payment
request throughout its existence within switching system.
payment_reference String [1..35] R
The Instruction ID is the unique identifier that is persisted in
the transactional database as the primary means of
subsequent reference for the Credit Transfer (that is, for
27
System Enquiries) The uniqueness of an instruction is
determined by the Instruction Identification and is based on
the format below Switching system will use the Instruction
ID to perform a check for a duplicate transaction within the
duplicate checking period and as a reference to the payment
instruction in other non-payment messages.
Format:
MMDDHHMMSSxxxxxxFFFFFYDDDHHnnnnnn
Pos 1-10: 10 digits Date/Time with format (GMT+7)
MMDDHHMMSS
Pos 11-16: 6 digits System Trace Number
Pos 17-22: 6 chars sending gateway bin code
Pos 23-35: 12 chars Unique Id (YDDDHHnnnnnn)
For QR Domestic: unique reference generated by
sending participant for each request max length 12
qr_string String [1..unbounded] R String QR code payment

payment Object R Payment information

Payment type, fixed to:
payment.type String 1..10 R
QR_PUSH
Payment generation method at
device, optional, values:
STATIC, DYNAMIC. Default
payment.generation_method String 1..10 O to STATIC.
For QR push service, tag 01:

11=STATIC, 12=DYNAMIC
Exchange rate calculated using
sending currency as the base
currency.
For example Thai inbound
from Singapore, SGD is base
payment.exchange_rate String 1..12 C currency
1 VND = 0.00134614 THB, the
value is 0.00134614
Format: 11 digits with 10
fractions
Indicator is fee indicator, tag

55
01 : Indicates Consumer should
payment.indicator String 1..2 C be prompted to enter tip
02 : Indicates that merchant
would mandatorily charge a
flat convenience fee
28
would charge a percentage
convenience fee
Fee fixed, tag 56
The convenience fee of a fixed
amount should be specified
here. This amount is expressed
as how the value appears,
amount “100.00” is defined as
payment.fee_fixed String 1..13 C
“100.00”, or amount “99.85” is
defined as “99.85”, or amount
“99.333” is defined as
“99.333” amount “99.3456” is
defined as “99.3456”
Note: 0 is not a valid value
Fee percentage, tag 57
The convenience percentage
should be specified here. This
amount is expressed as how the
value appears, amount “10.00”
payment.fee_percentage String 1..13 C
is defined as “10.00”, or
“9.85”
Note: 0 and 100 is not a valid
value.
Payment unique reference
generated by sending
participant for each request
For cross border payment QR:

Mapping with
Numeric
payment.payment_reference 1..35 R payment.payment_reference in
String
response of API
proxy_lookup_request.
For QR Domestic: unique
reference generated by sending
max length 12
An end-to-end reference for
tracing transaction between
parties, QR tag 62 sub tab 05
payment.end_to_end_reference String 1..25 C
This field is conditional,
required if presented in QR
message.
System trace audit number,
Numeric
payment.trace 1..6 O generated by sending
String
Receiving amount of the
payment, rounded to 2 decimal
amount String 1..12 R
digits if payment currency is
not VND
Receiving currency code of the
currency String 1..3 R transfer amount as an ISO 4217
alpha currency code. Eg: VND
participant Object R Participant object information
participant.originating_institution_id String 1..15 R Id of originating institution

Id of receiving institution,
participant.receiving_institution_id String 1..15 R placed in tag 38 sub tag 00 part
"acquirer id"
Merchant id, placed in 38 sub
participant.merchant_id String 1..19 R
tag 01 part "merchant id"
29
Merchant category code
defined by Napas. Detail values
participant.merchant_category_code String 1..4 R are in Appendix B - list of
merchant category Merchant
category code. Tag 52
Card acceptor / terminal id /

participant.card_acceptor_id String 1..8 R
wallet id
Card acceptor name, tag 59.

participant.card_acceptor_name String 1..22 C
message.
Card acceptor city, tag 60. This
participant.card_acceptor_city String 1..13 C field is conditional, required if
presented in QR message.
Card acceptor country, tag 58.
participant.card_acceptor_country String 1..3 C
message.
Card postal code, tag 61. This
participant.card_postal_code String 1..10 C field is conditional, required if
Card language preference, tag
64 sub tag 01. This field is
participant.card_language_preference String 1..2 C
conditional, required if
Card name alternate language,
tag 64 sub tag 02. This field is
participant.card_name_alternate_language String 1..25 C
Card city alternate language,
participant.card_city_alternate_language String 1..15 C
System payment specific is
participant.card_payment_system_specific String 1..99 O
addition info.
Recipient account information,
an encrypted format in
JWE/JWS of
account.data.profile as detailed
in Appendix A - Data
Protection.
recipient_account String R
Values for QR push service:
account.data.profile.type is
'RAW'
account.data.profile.pan is
mapped to tag 38 sub tag 01
part "merchant id"
recipient Object O Information about the recipient
recipient.first_name String 1..30 O First name of the recipient
recipient.middle_name String 1..30 O Middle name of the recipient
recipient.last_name String 1..40 O Last name of the recipient
recipient.full_name String 1..100 R Full name of the recipient
Date of birth of the recipient as
recipient.date_of_birth String 1..25 O
in ISO 8601 format
30
recipient.address Object O Address of the recipient
First line of the address of the
recipient.address.line1 String 1..50 O
recipient
Second line of the address of
the recipient
recipient.address.city String 1..50 O City of the recipient
recipient.address.country_subdivision String 1..30 O State or province of the sender.
recipient.address.postal_code Number 1..10 O Postal code of the sender
Country of the sender as an
recipient.address.country String 1..2 R
ISO alpha country code
recipient.address.phone String 1..15 O Sender phone number
recipient.address.email String 1..50 O Sender email address

Message a financial institution
additional_message String 1..999 O will associate to the transfer
and may display
order_info Object R Order information data group
Bill number by merchant or
order_info.bill_number String 1..25 R
consumer
order_info.mobile_number String 1..25 O Customer mobile number
Store specific information.
order_info.store_label String 1..25 C
message.
order_info.loyalty_number String 1..25 O Customer loyalty information
order_info.customer_label String 1..25 O Customer specific information

order_info.terminal_label String 1..25 O Terminal specific information
order_info.transaction_purpose String 1..25 O Transaction purpose
Customer additional data
request indicator
• "A" = Customer address
order_info.additional_data_request String 1..3 O
• "M" = Customer mobile
number
• "E" = Customer email
Additional information of
additional_info Object 0..1 O
transaction
Array of Detail information format
additional_info.instruction[i] 0..50 O
object key, value
additional_info.instruction[i].key String 0..200 R Part or field name info
additional_info.instruction[i].value String 0..200 R Value of part or field
The organization's global
identifier for QR code
AID String 1..32 O
generation under QR MVCo
standard
(2) Create Merchant Payment
This API is provided by NAPAS to Originating Institutions for creating the payment transaction
to transfer fund to merchant account on which consumer doing transaction. Napas will route the
payment transfer request to corresponding receivers through its payment network.
31
- If the Receiving Institution is NAPAS’s member banks: message will be routed as

current NAPAS payment network with banks.
- If the Receiving Institution is Payment Intermediary: NAPAS will send an outbound
API call to Payment Intermediary, follow current NAPAS API general contract standard
with payload message as described in 3.3.3 Create Merchant Payment.
Operation URL {NAPAS_API_BASE_URL}/{partner_id}/merchant/payment
HTTP Method POST
Protocol REST-JSON
header.operation QRPUSH

Provide a unique reference
number of funding transaction
payment.funding_reference String 1..12 O
from sending participant,
optional.
QR_PUSH

Initiation channel of the
payment request.
- 00: Unknown channel
- 01: ATM
- 02: Counter
- 03: POS
payment.channel String 1..2 R - 04: Internet Banking
- 05: Mobile Application
- 06: SMS Banking
- 07: Others
Default value 05 for e-wallet

application.
The serial number of a device
payment.device_id String 1..99 O
initiating the transfer, optional.
Location where the transaction
payment.location String 1..99 O is initiated in (latitude,
longitude) in decimal format,
32
optional. Eg:
(21.0228161,105.801944)
Local date and time when the
transaction is submitted as in
ISO 8601 format with time
payment.transaction_local_date_time Date 1..25 R zone. The date and time should
exact to milliseconds.
Eg: 2019-03-
25T10:32:24.634+07:00
The amount of the payment is
in local currency, rounded to 2
decimal digits if payment
payment.interbank_amount String 1..12 C currency is not VND.
For cross border payment QR

is required
Currency code of the transfer
amount as an ISO 4217 alpha
currency code
payment.interbank _currency String 1..3 C
is required
currency.
currency
1 VND = 0.00134614 THB,
payment.exchange_rate String 1..12 C the value is 0.00134614
fractions

Mapping with exchange_rate
in response of API
55
01 : Indicates Consumer
should be prompted to enter tip
payment.indicator String 1..2 C
convenience fee
Fee fixed, tag 56
“100.00”, or amount “99.85” is
“99.333” amount “99.3456” is
amount is expressed as how
33
the value appears, amount
“10.00” is defined as “10.00”,
or amount “9.85” is defined as
“9.85”
value.
Numeric
payment.trace 1..6 R generated by sending
String

Mapping with
Numeric
String
response of API
max length 12
message.
not VND
transfer amount as an ISO
currency String 1..3 R
4217 alpha currency code. Eg:
VND
JWE/JWS of
Protection.
sender_account String R
'RAW'
mapped to customer account
which funding transaction.
sender Object R Sender information, optional
sender.first_name String 1..30 O First name of the sender
sender.middle_name String 1..30 O Middle name of the sender.
sender.last_name String 1..40 O Last name of the sender.
sender.full_name String 1..100 R Full name of the sender.
Date of birth of the sender as
sender.date_of_birth String 1..25 O
in ISO 8601 format
sender.address Object O Address of the sender
sender.address.line1 String 1..50 R
sender
sender.address.line2 String 1..50 O
the sender
34
sender.address.city String 1..50 O City of the sender
sender.address.country_subdivision String 1..30 O State or province of the sender.
sender.address.postal_code String 1..10 O Postal code of the sender
sender.address.country String 1..2 R
sender.address.phone String 1..15 O Sender phone number
sender.address.email String 1..50 O Sender email address
"acquirer id"
Merchant id, placed in 38 sub
defined by Napas. Detail
participant.merchant_category_code String 1..4 R
values are in Appendix B - list
of merchant category code
wallet id
message.
message.
addition info.
JWE/JWS of
recipient_account String R Protection.

'RAW'
35
part "merchant id"

in ISO 8601 format
recipient
the recipient
and may display
consumer
message.
request indicator
number
transaction
object key, value
36


System generated unique
payment.reference String 1..40 R
payment identifier by Napas
Authorization Identification
payment.authorization_code String 1..6 C
Response, required if success
Provide a unique reference
payment.funding_reference String 1..12 O
optional.
QR_PUSH

Initiation channel of the
payment request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
Location where the transaction
is initiated in (latitude,
payment.location String 1..99 O longitude) in decimal format,
optional. Eg:
(21.0228161,105.801944)
payment.transaction_local_date_time Date 1..25 R zone. The date and time should
Eg: 2019-03-
25T10:32:24.634+07:00
37
The amount of the payment is
payment.interbank_amount String 1..12 C currency is not VND.

is required
currency code
is required
currency.
currency
1 VND = 0.00134614 THB, the
payment.exchange_rate String 1..12 C value is 0.00134614
fractions

Mapping with exchange_rate in
response of API
55
be prompted to enter tip
convenience fee
Fee fixed, tag 56
“100.00”, or amount “99.85” is
“99.333” amount “99.3456” is
“9.85”
value.
Numeric
payment.trace 1..6 R generated by sending
String
38

Mapping with
Numeric
String
response of API
max length 12
message.
not VND
Amount of the settlement,
settlement_amount String 1..12 O rounded to 2 decimal digits if
settlement currency is not VND
Settlement currency as an ISO
settlement_currency String 1..3 O
alpha currency code
Date of settlement as in ISO
settlement_date String R
8601 format
JWE/JWS of
Protection.
'RAW'
Date of birth of the sender as in
ISO 8601 format
sender
the sender
39
"acquirer id"
Merchant id, placed 38 sub tag
01 part "merchant id"
defined by Napas. Detail values
are in Appendix B - list of
merchant category code
wallet id
message.
message.
addition info.
JWE/JWS of
Protection.
'RAW'
part "merchant id"
40
in ISO 8601 format
recipient
the recipient
and may display
consumer
message.
request indicator
number
transaction
object key, value
(3) Create Merchant Void Payment

This API is provided by NAPAS to Originating Institutions for creating the of the void payment
transaction to transfer fund to consumer account on which merchant revert. Napas will route the
void payment transfer request to corresponding receivers through its payment network.
41
- If the Receiving Institution is NAPAS’s member banks: message will be routed as
current NAPAS payment network with banks.
- If the Receiving Institution is Payment Intermediary: NAPAS will send an outbound
API call to Payment Intermediary, follow current NAPAS API general contract standard
with payload message as described in 3.3.3 Create Merchant Void Payment.
Operation URL {NAPAS_API_BASE_URL}/{partner_id}/merchant/void
HTTP Method POST
Protocol REST-JSON
header.operation QRVOID

Field
type
Payment unique reference generated by sending
Format:
YYYYMMDDHHmmss<GW_BIC>nnnnnnnnnnnnnnn
payment_reference String 1..35 R Ex: 20200819151320NAPASVNV0000000000001
Pos 1-8: Date with format YYYYMMDD
Pos 9-14: Time with format HHmmss
Pos 15-22: sending switch code
Pos 23-35: Unique Id
original Object R Original payment information
original.payment Object R Payment information
original.payment.funding_reference Provide a unique reference number of funding
String 1..12 O
transaction from sending participant, optional.
original.payment.type String 1..10 R Payment type, fixed to: QR_PUSH
original.payment.generation_method Payment generation method at device, optional, values:
STATIC, DYNAMIC. Default to STATIC.
String 1..10 O
For QR push service, tag 01: 11=STATIC,
12=DYNAMIC
original.payment.channel
Initiation channel of the payment request.
- 01: ATM
- 02: Counter
- 03: POS
String 1..2 R - 04: Internet Banking
- 06: SMS Banking
- 07: Others
Default value 05 for e-wallet application.
original.payment.device_id The serial number of a device initiating the transfer,

String 1..99 O
optional.
42
original.payment.location Location where the transaction is initiated in (latitude,
String 1..99 O longitude) in decimal format, optional. Eg:
(21.0228161,105.801944)
original.payment.transaction_local_date_time Local date and time when the transaction is submitted
as in ISO 8601 format with time zone. The date and
Date 1..25 R
time should exact to milliseconds.
Eg: 2019-03-25T10:32:24.634+07:00
original.payment.interbank_amount The amount of the payment is in local currency,
rounded to 2 decimal digits if payment currency is not
String 1..12 C VND.
For cross border payment QR is required

original.payment.interbank _currency Currency code of the transfer amount as an ISO 4217
alpha currency code
String 1..3 C
For cross border payment QR is required
original.payment.exchange_rate Exchange rate calculated using sending currency as the
base currency.
For example Thai inbound from Singapore, SGD is
base currency
1 VND = 0.00134614 THB, the value is 0.00134614
String 1..12 C
Format: 11 digits with 10 fractions

Mapping with exchange_rate in response of API
original.payment.indicator Indicator is fee indicator, tag 55
01 : Indicates Consumer should be prompted to enter
tip
String 1..2 C 02 : Indicates that merchant would mandatorily charge
a flat convenience fee
03 : Indicates that merchant would charge a percentage
convenience fee
original.payment.fee_fixed Fee fixed, tag 56
The convenience fee of a fixed amount should be
specified here. This amount is expressed as how the
value appears, amount “100.00” is defined as “100.00”,
String 1..13 C
or amount “99.85” is defined as “99.85”, or amount
“99.333” is defined as “99.333” amount “99.3456” is
original.payment.fee_percentage Fee percentage, tag 57
The convenience percentage should be specified here.
This amount is expressed as how the value appears,
String 1..13 C
amount “10.00” is defined as “10.00”, or amount
“9.85” is defined as “9.85”
Note: 0 and 100 is not a valid value.
original.payment.trace Numeric System trace audit number, generated by sending
1..6 R
String participant for each request
original.payment.payment_reference Payment unique reference generated by sending
Numeric
1..35 R
String For cross border payment QR:
Mapping with payment.payment_reference in response
of API proxy_lookup_request.
original.payment.end_to_end_reference An end-to-end reference for tracing transaction
String 1..25 O
between parties, QR tag 62 sub tab 05
original.amount Receiving amount of the payment, rounded to 2
String 1..12 R
decimal digits if payment currency is not VND
original.currency Receiving currency code of the transfer amount as an
String 1..3 R
ISO 4217 alpha currency code. Eg: VND
43
original.sender_account Recipient account information, an encrypted format in
JWE/JWS of account.data.profile as detailed in
Appendix A - Data Protection.
String R
account.data.profile.type is 'RAW'
account.data.profile.pan is mapped to customer account
original.sender Object R Sender information, optional
original.sender.first_name String 1..30 O First name of the sender
original.sender.middle_name String 1..30 O Middle name of the sender.
original.sender.last_name String 1..40 O Last name of the sender.
original.sender.full_name String 1..100 R Full name of the sender.
original.sender.date_of_birth String 1..25 O Date of birth of the sender as in ISO 8601 format
original.sender.address Object O Address of the sender
original.sender.address.line1 String 1..50 R First line of the address of the sender
original.sender.address.line2 String 1..50 O Second line of the address of the sender
original.sender.address.city String 1..50 O City of the sender
original.sender.address.country_subdivision String 1..30 O State or province of the sender.
original.sender.address.postal_code String 1..10 O Postal code of the sender
original.sender.address.country String 1..2 R Country of the sender as an ISO alpha country code
original.sender.address.phone String 1..15 O Sender phone number
original.sender.address.email String 1..50 O Sender email address
original.participant Object R Participant object information
original.participant.originating_institution_id String 1..15 R Id of originating institution
original.participant.receiving_institution_id Id of receiving institution, placed tag 38 sub tag 00 part
String 1..15 R
"acquirer id"
original.participant.merchant_id String 1..19 R Merchant id, placed in 38 sub tag 01 part "merchant id"
original.participant.merchant_category_code Merchant category code defined by Napas. Detail
String 1..4 R values are in Appendix B - list of merchant category
code
original.participant.card_acceptor_id String 1..8 R Card acceptor / terminal id / wallet id
original.participant.card_acceptor_name Card acceptor name, tag 59. This field is conditional,
String 1..22 C
required if presented in QR message.
original.participant.card_acceptor_city Card acceptor city, tag 60. This field is conditional,
String 1..13 C
original.participant.card_acceptor_country Card acceptor country, tag 58. This field is conditional,
String 1..3 C
original.participant.card_postal_code Card postal code, tag 61. This field is conditional,
String 1..10 C
original.participant.card_language_preference Card language preference, tag 64 sub tag 01. This field
String 1..2 C
is conditional, required if presented in QR message.
original.participant.card_name_alternate_language Card name alternate language, tag 64 sub tag 02. This
String 1..25 C field is conditional, required if presented in QR
message.
original.participant.card_city_alternate_language Card city alternate language, tag 64 sub tag 03. This
String 1..15 C field is conditional, required if presented in QR
message.
original.participant.card_payment_system_specific String 1..99 O System payment specific is addition info.
44
Recipient account information, an encrypted format in
JWE/JWS of account.data.profile as detailed in
original.recipient_account String R
account.data.profile.pan is mapped to tag 38 sub tag 01
part "merchant id"
original.recipient Object O Information about the recipient
original.recipient.first_name String 1..30 O First name of the recipient
original.recipient.middle_name String 1..30 O Middle name of the recipient
original.recipient.last_name String 1..40 O Last name of the recipient
original.recipient.full_name String 1..100 R Full name of the recipient
original.recipient.date_of_birth String 1..25 O Date of birth of the recipient as in ISO 8601 format
original.recipient.address Object O Address of the recipient
original.recipient.address.line1 String 1..50 O First line of the address of the recipient
original.recipient.address.line2 String 1..50 O Second line of the address of the recipient
original.recipient.address.city String 1..50 O City of the recipient
original.recipient.address.country_subdivision String 1..30 O State or province of the sender.
original.recipient.address.postal_code Number 1..10 O Postal code of the sender
original.recipient.address.country String 1..2 R Country of the sender as an ISO alpha country code
original.recipient.address.phone String 1..15 O Sender phone number
original.recipient.address.email String 1..50 O Sender email address
original.additional_message Message a financial institution will associate to the
String 1..999 O
transfer and may display
original.order_info Object R Order information data group
original.order_info.bill_number String 1..25 R Bill number by merchant or consumer
original.order_info.mobile_number String 1..25 O Customer mobile number
original.order_info.store_label String 1..25 O Store specific information
original.order_info.loyalty_number String 1..25 O Customer loyalty information
original.order_info.customer_label String 1..25 O Customer specific information
original.order_info.terminal_label String 1..25 O Terminal specific information
original.order_info.transaction_purpose String 1..25 O Transaction purpose
original.order_info.additional_data_request Customer additional data request indicator
String 1..3 O
• "M" = Customer mobile number
additional_info Object 0..1 O Additional information of transaction
Array of
additional_info.instruction[i] 0..50 O Detail information format key, value
object

45

payment_reference String R generated by sending
original.payment.reference System generated unique
String 1..40 R
payment identifier by Napas
original.payment.authorization_code Authorization Identification
String 1..6 C
original.payment.funding_reference Provide a unique reference
String 1..12 O
optional.
original.payment.type Payment type, fixed to:
String 1..10 R
QR_PUSH
original.payment.generation_method Payment generation method at
String 1..10 O to STATIC.

original.payment.channel Initiation channel of the
payment request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
original.payment.device_id The serial number of a device
String 1..99 O
original.payment.location Location where the transaction
is initiated in (latitude,
String 1..99 O longitude) in decimal format,
optional. Eg:
(21.0228161,105.801944)
original.payment.transaction_local_date_time Local date and time when the
Date 1..25 R zone. The date and time should
Eg: 2019-03-
25T10:32:24.634+07:00
original.payment.interbank_amount The amount of the payment is
String 1..12 C
46
currency is not VND.

is required
original.payment.interbank _currency Currency code of the transfer
currency code
String 1..3 C
is required
original.payment.exchange_rate Exchange rate calculated using
currency.
currency
1 VND = 0.00134614 THB,
String 1..12 C the value is 0.00134614
fractions

response of API
original.payment.indicator Indicator is fee indicator, tag
55
be prompted to enter tip
String 1..2 C
convenience fee
String 1..13 C
“100.00”, or amount “99.85” is
“99.333” amount “99.3456” is
String 1..13 C
“9.85”
value.
original.payment.trace System trace audit number,
Numeric
1..6 R generated by sending
String
original.payment.payment_reference Payment unique reference
Numeric
1..35 R generated by sending
String
47
Mapping with
payment.payment_reference in
response of API
original.payment.end_to_end_reference An end-to-end reference for
String 1..25 O tracing transaction between
original.amount Receiving amount of the
String 1..12 R
not VND
original.currency Receiving currency code of the
String 1..3 R transfer amount as an ISO 4217
original.settlement_amount Amount of the settlement,
rounded to 2 decimal digits if
String 1..12 O
settlement currency is not
VND
original.settlement_currency Settlement currency as an ISO
String 1..3 O
alpha currency code
original.settlement_date Date of settlement as in ISO
String R
8601 format
original.sender_account Recipient account information,
JWE/JWS of
Protection.
String R
'RAW'
original.sender.date_of_birth Date of birth of the sender as in
String 1..25 O
ISO 8601 format
original.sender.address.line1 First line of the address of the
String 1..50 R
sender
original.sender.address.line2 Second line of the address of
String 1..50 O
the sender
original.sender.address.country Country of the sender as an
String 1..2 R
48
original.participant.receiving_institution_id Id of receiving institution,
String 1..15 R placed in tag 38 sub tag 00 part
"acquirer id"
original.participant.merchant_id Merchant id, placed in 38 sub
String 1..19 R
original.participant.merchant_category_code Merchant category code
defined by Napas. Detail
String 1..4 R
values are in Appendix B - list
of merchant category code
original.participant.card_acceptor_id Card acceptor / terminal id /
String 1..8 R
wallet id
original.participant.card_acceptor_name Card acceptor name, tag 59.
String 1..22 C
message.
original.participant.card_acceptor_city Card acceptor city, tag 60. This
String 1..13 C field is conditional, required if
original.participant.card_acceptor_country Card acceptor country, tag 58.
String 1..3 C
message.
original.participant.card_postal_code Card postal code, tag 61. This
original.participant.card_language_preference Card language preference, tag
String 1..2 C
original.participant.card_name_alternate_language Card name alternate language,
String 1..25 C
original.participant.card_city_alternate_language Card city alternate language,
String 1..15 C
original.participant.card_payment_system_specific System payment specific is
String 1..99 O
addition info.
JWE/JWS of
Protection.
original.recipient_account String R
'RAW'
part "merchant id"
original.recipient.date_of_birth Date of birth of the recipient as
String 1..25 O
in ISO 8601 format
49
original.recipient.address.line1 First line of the address of the
String 1..50 O
recipient
original.recipient.address.line2 Second line of the address of
String 1..50 O
the recipient
original.recipient.address.country Country of the sender as an
String 1..2 R
original.additional_message Message a financial institution
String 1..999 O will associate to the transfer
and may display
original.order_info.bill_number Bill number by merchant or
String 1..25 R
consumer
original.order_info.additional_data_request Customer additional data
request indicator
String 1..3 O
number
transaction
Array of Detail information format key,
object value
3.3 Message Format for OUTGOING Request

This section describe the business message format for all outgoing request from Napas to
partners. The object models in this section are used in payload part of request and response
message follow by API General Contract.
These messages format are used by default. Customization might need depend on individual
cases.
3.3.1 Create Transaction Inquiry
50
This API is provided by NAPAS to Originating Institutions for querying the payment
transaction status in case of unclear failure or timeout. Napas will route the payment inquiry
request to corresponding receivers through its payment network.
The current support of this API only include Napas Ecommerce Payment System.
Operation URL {PARTNER_SERVICE_URL}
HTTP Method POST
Protocol REST-JSON
header.operation TRANSACTION_INQUIRY

Field
type
sender String 1..8 R Id of sending institution of inquiry transaction
receiver String 1..8 R Id of receiving institution of original transaction
id_message String 1..35 Id that identifies a message is unique.
For ITMX QR, you must follow the rules of ITMX:
ITMX Format:
MNYYYYMMDDHHmmssbbbnnnnnnnnnnnnnnnn
R Pos. 02-02 - Node Identification (1 numeric
character)
Pos: 20 -35 - unique serial number (identical to the
number use in the BAH)
datetime String 1..25 Date and time of sending query transaction

R VD: 2019-03-25T10:32:24.634+07:00
type String 1..10 Valid value are:
QR_PUSH
CASHIN
R
CASHOUT
EFT
trace String 1..6 R System trace audit number of original transaction
txId String 1..35 TxId of the transaction that inquiry the state.
O At the beginning of the organization issue the VN

call ESB, this value does not exist
51
At the beginning of the ESB call request to ITMX,
this value should be included in the message
camt.005
The first ITMX call request camt.005 to ESB needs

this value
id_orig_payment String 1..35 The EndToEndId of the parent transaction needs to
R query the state. Unique id number to identify end to
end payment transactions.
orig_datetime String 1..25 R Date and time of the original payment transaction
orig_amount Number 1..12 R Amount of original payment transaction
orig_ccy String 1..3 R Currency of the original payment transaction
original_originating_institution String 1..8 The organization sending the original payment

R
transaction
original_receiving_institution String 1..8 Organization receiving the original payment
R
transaction
original_debtor_institution String 1..19 R Debit institution of the original transaction
debtor_account String The debit account number of the original

original_creditor_institution String 1..19 R Credit organization of the original transaction
creditor_account String The credit account number of the original


sender String 1..8 R Id of sending institution of inquiry
transaction
receiver String 1..8 R Id of receiving institution of original
transaction
id_message String 1..35 R Id that identifies a message is unique.
For ITMX QR, you must follow the rules of

ITMX:
ITMX Format:
MNYYYYMMDDHHmmssbbbnnnnnnnnn
nnnnnnn
52
Pos. 02-02 - Node Identification (1 numeric
character)
Pos: 20 -35 - unique serial number (identical
to the number use in the BAH)
datetime String 1..25 R The date and time of sending the query
transaction result response
VD: 2019-03-25T10:32:24.634+07:00
trace String 1..6 O System trace audit number of original
transaction
txId String 1..35 R TxId of the transaction that inquiry the state.
id_orig_payment String 1..35 O The EndToEndId of the parent transaction

needs to query the state. Unique id number
to identify end to end payment transactions.
orig_resp_datetime String 1..25 O Date and time of the original payment

transaction
transaction_code String 1..6 O Status Code of the original payment
transaction
description String 1..100 O Description for the status code of the
original transaction
error_code String 1..6 O Error code request payment enquiry
error_desc String 1..100 O Error description request payment enquiry
orig_amount Number 1..12 O Amount of original payment transaction
orig_ccy String 1..3 O Currency of the original payment

transaction
settle_date Date 1..25 O The settlement date of the original
transaction, if the original transaction is
settled
3.3.2 Create Proxy Lookup Request

In case of Payment Intermediary plays a role as receiving Institution, NAPAS will send the
lookup request as outbound APIs with following format.
HTTP Method POST
Protocol REST-JSON
53
header.operation QRLOOKUP

Field
type
The Payment Reference is assigned by the Debtor Bank
to uniquely identify a single Credit Transfer within a
payment request throughout its existence within
switching system. The Instruction ID is the unique
identifier that is persisted in the transactional database
as the primary means of subsequent reference for the
Credit Transfer (that is, for System Enquiries) The
uniqueness of an instruction is determined by the
Instruction Identification and is based on the format
below Switching system will use the Instruction ID to
perform a check for a duplicate transaction within the
duplicate checking period and as a reference to the
payment_reference String [1..35] R payment instruction in other non-payment messages.
Format:
YYYYMMDDHHmmss<GW_BIC>nnnnnnnnnnnnnnn
Ex: 20200819151320NAPASVNV0000000000001
Pos 1-8: Date with format YYYYMMDD
Pos 9-14: Time with format HHmmss
For QR Domestic: unique reference generated
by sending participant for each request max
length 12
qr_string String [1..unbounded] R String QR code payment


Field
type
payment.type String 1..10 R Payment type, fixed to: QR_PUSH
device, optional, values: STATIC,
DYNAMIC. Default to STATIC.
payment.generation_method String 1..10 O
payment.exchange_rate String 1..12 C sending currency as the base
currency.
54
For example Thai inbound from
Singapore, SGD is base currency
1 VND = 0.00134614 THB, the
value is 0.00134614
Indicator is fee indicator, tag 55

01 : Indicates Consumer should be
prompted to enter tip
02 : Indicates that merchant would
mandatorily charge a flat
convenience fee
charge a percentage convenience fee
Fee fixed, tag 56

amount should be specified here.
This amount is expressed as how the
value appears, amount “100.00” is
payment.fee_fixed String 1..13 C defined as “100.00”, or amount
“99.85” is defined as “99.85”, or
“99.333” amount “99.3456” is

The convenience percentage should
be specified here. This amount is
expressed as how the value appears,
“10.00”, or amount “9.85” is defined
as “9.85”
Payment unique reference generated
by sending participant for each
request

Mapping with
Numeric
String
response of API
participant for each request max
length 12
An end-to-end reference for tracing
transaction between parties, QR tag
payment.end_to_end_reference String 1..25 C 62 sub tab 05
This field is conditional, required if
Numeric
payment.trace 1..6 O generated by sending participant for
String
each request
Receiving amount of the payment,
amount String 1..12 R rounded to 2 decimal digits if
payment currency is not VND
alpha currency code Eg: VND
55
Id of receiving institution, placed in

participant.receiving_institution_id String 1..15 R
tag 38 sub tag 00 part "acquirer id"
Merchant id, placed in 38 sub tag 01
part "merchant id"
Merchant category code defined by
Napas. Detail values are in
participant.merchant_category_code String 1..4 R Appendix B - list of merchant
category Merchant category code.
Tag 52
Card acceptor / terminal id / wallet
id
Card acceptor name, tag 59. This
participant.card_acceptor_name String 1..22 C field is conditional, required if
Card acceptor city, tag 60. This field

participant.card_acceptor_city String 1..13 C is conditional, required if presented
in QR message.
Card acceptor country, tag 58. This

participant.card_acceptor_country String 1..3 C field is conditional, required if
Card postal code, tag 61. This field
participant.card_postal_code String 1..10 C is conditional, required if presented
in QR message.
Card language preference, tag 64
sub tag 01. This field is conditional,
message.
Card name alternate language, tag
conditional, required if presented in
QR message.
Card city alternate language, tag 64
message.
System payment specific is addition
info.
Recipient account information, an
encrypted format in JWE/JWS of
account.data.profile as detailed in
account.data.profile.pan is mapped
to tag 38 sub tag 01 part "merchant
id"
Date of birth of the recipient as in
ISO 8601 format
56
recipient
Second line of the address of the
recipient

Country of the sender as an ISO
alpha country code
Message a financial institution will
additional_message String 1..999 O associate to the transfer and may
display

consumer
order_info.store_label String 1..25 C This field is conditional, required if
Customer additional data request
indicator
order_info.additional_data_request String 1..3 O • "A" = Customer address
transaction
Array of
object
The organization's global identifier
AID String 1..32 O for QR code generation under QR
MVCo standard
3.3.3 Create Merchant Payment

In case of Payment Intermediary plays a role as receiving Institution, NAPAS will send the
payment request as outbound APIs with following format.
57
HTTP Method POST
Protocol REST-JSON
header.operation QRPUSH

Field
type
Provide a unique reference number
payment.funding_reference String 1..12 O of funding transaction from sending
participant, optional.
Initiation channel of the payment
request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
Location where the transaction is
initiated in (latitude, longitude) in
payment.location String 1..99 O
decimal format, optional. Eg:
(21.0228161,105.801944)
transaction is submitted as in ISO
8601 format with time zone. The
payment.transaction_local_date_time Date 1..25 R date and time should exact to
milliseconds.
Eg: 2019-03-
25T10:32:24.634+07:00
The amount of the payment is in
local currency, rounded to 2 decimal
digits if payment currency is not
payment.interbank_amount String 1..12 C VND.
For cross border payment QR is

required
58
Currency code of the transfer amount
as an ISO 4217 alpha currency code
required
currency.
1 VND = 0.00134614 THB, the
payment.exchange_rate String 1..12 C value is 0.00134614

response of API
convenience fee
Fee fixed, tag 56
“99.85” is defined as “99.85”, or
“99.333” amount “99.3456” is
as “9.85”
Numeric
payment.trace 1..6 R generated by sending participant for
String
each request
request

Numeric Mapping with
payment.payment_reference 1..35 R
String payment.payment_reference in
response of API
For QR Domestic: unique reference
generated by sending participant for
each request max length 12
payment.end_to_end_reference String 1..25 C transaction between parties, QR tag
62 sub tab 05. This field is
59
QR message.
Amount of the settlement, rounded to
settlement_amount String 1..12 O 2 decimal digits if settlement
currency is not VND
Settlement currency as an ISO alpha
currency code
Date of settlement as in ISO 8601
format
account.data.profile.pan is mapped to
customer account which funding
transaction.
Date of birth of the sender as in ISO
8601 format
sender.address.line1 String 1..50 R First line of the address of the sender
sender
alpha country code
part "merchant id"
participant.merchant_category_code String 1..4 R Napas. Detail values are in Appendix
B - list of merchant category code
id
60
in QR message.
Card postal code, tag 61. This field is

participant.card_postal_code String 1..10 C conditional, required if presented in
QR message.
Card language preference, tag 64 sub

participant.card_language_preference String 1..2 C tag 01. This field is conditional,
Card name alternate language, tag 64
participant.card_name_alternate_language String 1..25 C sub tag 02. This field is conditional,
participant.card_city_alternate_language String 1..15 C sub tag 03. This field is conditional,
info.
tag 38 sub tag 01 part "merchant id"
ISO 8601 format
recipient
recipient

alpha country code
61
display
consumer
Store specific information. This field
order_info.store_label String 1..25 C is conditional, required if presented
in QR message.

indicator
Array of
object


Field
type
System generated unique payment
payment.reference String 1..40 R
identifier by Napas
62
Authorization Identification
payment.authorization_code String 1..6 C
Provide a unique reference number
payment.funding_reference String 1..12 O of funding transaction from sending
Initiation channel of the payment
request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
Location where the transaction is
payment.location String 1..99 O
(21.0228161,105.801944)
payment.transaction_local_date_time Date 1..25 R date and time should exact to
milliseconds.
Eg: 2019-03-
25T10:32:24.634+07:00
The amount of the payment is in
payment.interbank_amount String 1..12 C VND.

required
currency code
required
currency.
payment.exchange_rate String 1..12 C
1 VND = 0.00134614 THB, the
value is 0.00134614
63
response of API
convenience fee
Fee fixed, tag 56
“99.85” is defined as “99.85”, or
“99.333” amount “99.3456” is
as “9.85”
Numeric
payment.trace 1..6 R generated by sending participant for
String
each request
request

Mapping with
Numeric
String
response of API
participant for each request max
length 12
transaction between parties, QR tag
payment.end_to_end_reference String 1..25 C 62 sub tab 05
This field is conditional, required if
Amount of the settlement, rounded
settlement_amount String 1..12 O to 2 decimal digits if settlement
currency is not VND
Settlement currency as an ISO alpha
currency code
Date of settlement as in ISO 8601
format
64
to customer account which funding
transaction.
Date of birth of the sender as in ISO
8601 format
sender
sender
alpha country code
part "merchant id"
Appendix B - list of merchant
category code
id
in QR message.
Card postal code, tag 61. This field
participant.card_postal_code String 1..10 C is conditional, required if presented
in QR message.
Card language preference, tag 64
message.
65
Card name alternate language, tag
QR message.
message.
info.
id"
ISO 8601 format
recipient
recipient
alpha country code
display
consumer
order_info.store_label String 1..25 C This field is conditional, required if
66
indicator
transaction
Array of
object
3.3.1 Create Merchant Void Payment

In case of Payment Intermediary plays a role as receiving Institution, NAPAS will send the void
payment request as outbound APIs with following format.
HTTP Method POST
Protocol REST-JSON
header.operation QRVOID

Field
type
request
Format:
YYYYMMDDHHmmss<GW_BIC>
nnnnnnnnnnnnnnn
Ex:
payment_reference String 1..35 R
20200819151320NAPASVNV00000
00000001
Pos 1-8: Date with format
YYYYMMDD
Pos 9-14: Time with format
HHmmss
original.payment.funding_reference Provide a unique reference number
String 1..12 O of funding transaction from sending
67
String 1..10 O
original.payment.channel Initiation channel of the payment
request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
String 1..99 O
original.payment.location Location where the transaction is
String 1..99 O
(21.0228161,105.801944)
Date 1..25 R date and time should exact to
milliseconds.
Eg: 2019-03-
25T10:32:24.634+07:00
original.payment.interbank_amount The amount of the payment is in
String 1..12 C VND.

required
original.payment.interbank _currency Currency code of the transfer amount
as an ISO 4217 alpha currency code
String 1..3 C
required
currency.
1 VND = 0.00134614 THB, the
String 1..12 C value is 0.00134614

response of API
String 1..2 C
convenience fee
68
String 1..13 C defined as “100.00”, or amount
“99.85” is defined as “99.85”, or
“99.333” amount “99.3456” is
String 1..13 C
as “9.85”
Numeric
1..6 R generated by sending participant for
String
each request
original.payment.payment_reference Payment unique reference generated
request
Numeric
1..35 R For cross border payment QR:
String
Mapping with
response of API
original.payment.end_to_end_reference An end-to-end reference for tracing
String 1..25 O transaction between parties, QR tag
62 sub tab 05
original.amount Receiving amount of the payment,
String 1..12 R rounded to 2 decimal digits if
alpha currency code
original.sender_account Recipient account information, an
String R
customer account which funding
transaction.
original.sender.middle_name
String 1..30 O Middle name of the sender.
69
original.sender.date_of_birth Date of birth of the sender as in ISO
String 1..25 O
8601 format
original.sender.address.line1 String 1..50 R First line of the address of the sender
original.sender.address.line2 Second line of the address of the
String 1..50 O
sender
original.sender.address.country Country of the sender as an ISO
String 1..2 R
alpha country code
original.participant.receiving_institution_id Id of receiving institution, placed in
String 1..15 R
original.participant.merchant_id Merchant id, placed in 38 sub tag 01
String 1..19 R
part "merchant id"
original.participant.merchant_category_code Merchant category code defined by
String 1..4 R Napas. Detail values are in Appendix
B - list of merchant category code
original.participant.card_acceptor_id Card acceptor / terminal id / wallet
String 1..8 R
id
original.participant.card_acceptor_name Card acceptor name, tag 59. This
original.participant.card_acceptor_city Card acceptor city, tag 60. This field
String 1..13 C is conditional, required if presented
in QR message.
original.participant.card_acceptor_country Card acceptor country, tag 58. This
original.participant.card_postal_code Card postal code, tag 61. This field is
String 1..10 C conditional, required if presented in
QR message.
original.participant.card_language_preference Card language preference, tag 64 sub
String 1..2 C tag 01. This field is conditional,
original.participant.card_name_alternate_language Card name alternate language, tag 64
String 1..25 C sub tag 02. This field is conditional,
original.participant.card_city_alternate_language

String 1..15 C sub tag 03. This field is conditional,
original.participant.card_payment_system_specific System payment specific is addition

String 1..99 O
info.
original.recipient_account Recipient account information, an
String R account.data.profile as detailed in
70
tag 38 sub tag 01 part "merchant id"
original.recipient.date_of_birth Date of birth of the recipient as in
String 1..25 O
ISO 8601 format
String 1..50 O
recipient
original.recipient.address.line2 Second line of the address of the
String 1..50 O
recipient
original.recipient.address.country Country of the sender as an ISO
String 1..2 R
alpha country code
original.recipient.address.phone
String 1..15 O Sender phone number
original.additional_message Message a financial institution will
String 1..999 O associate to the transfer and may
display
String 1..25 R
consumer
original.order_info.terminal_label
String 1..25 O Terminal specific information
original.order_info.transaction_purpose
String 1..25 O Transaction purpose
original.order_info.additional_data_request Customer additional data request

indicator
String 1..3 O • "A" = Customer address
Array of
object
71

payment_reference String R generated by sending participant
for each request
original.payment.reference System generated unique payment
String 1..40 R
identifier by Napas
original.payment.authorization_code Authorization Identification
String 1..6 C
original.payment.funding_reference Provide a unique reference number
String 1..12 O of funding transaction from
sending participant, optional.
String 1..10 O
original.payment.channel Initiation channel of the payment
request.
- 01: ATM
- 02: Counter
- 03: POS
- 06: SMS Banking
- 07: Others

application.
String 1..99 O
original.payment.location Location where the transaction is
String 1..99 O
(21.0228161,105.801944)
Date 1..25 R date and time should exact to
milliseconds.
Eg: 2019-03-
25T10:32:24.634+07:00
72
original.payment.interbank_amount The amount of the payment is in
local currency, rounded to 2
decimal digits if payment currency
String 1..12 C is not VND.

required
original.payment.interbank _currency Currency code of the transfer
currency code
String 1..3 C
required
currency.
1 VND = 0.00134614 THB, the
String 1..12 C value is 0.00134614

response of API
String 1..2 C mandatorily charge a flat
convenience fee
charge a percentage convenience
fee
This amount is expressed as how
the value appears, amount
String 1..13 C “100.00” is defined as “100.00”, or
“99.85”, or amount “99.333” is
defined as “99.333” amount
“99.3456” is defined as “99.3456”
String 1..13 C value appears, amount “10.00” is
“9.85” is defined as “9.85”
value.
Numeric
1..6 R generated by sending participant
String
for each request
original.payment.payment_reference Payment unique reference
generated by sending participant
Numeric
1..35 R for each request
String
73
Mapping with
response of API
original.payment.end_to_end_reference An end-to-end reference for
String 1..25 O tracing transaction between parties,
QR tag 62 sub tab 05
original.amount Receiving amount of the payment,
String 1..12 R rounded to 2 decimal digits if
alpha currency code
original.settlement_amount Amount of the settlement, rounded
String 1..12 O to 2 decimal digits if settlement
currency is not VND
original.settlement_currency Settlement currency as an ISO
String 1..3 O
alpha currency code
original.settlement_date Date of settlement as in ISO 8601
String R
format
original.sender_account Recipient account information, an
String R
to customer account which funding
transaction.
original.sender.date_of_birth Date of birth of the sender as in
String 1..25 O
ISO 8601 format
original.sender.address.line1 First line of the address of the
String 1..50 R
sender
original.sender.address.line2 Second line of the address of the
String 1..50 O
sender
original.sender.address.country Country of the sender as an ISO
String 1..2 R
alpha country code
original.participant.receiving_institution_id Id of receiving institution, placed
String 1..15 R in tag 38 sub tag 00 part "acquirer
id"
original.participant.merchant_id Merchant id, placed in 38 sub tag
String 1..19 R
01 part "merchant id"
74
original.participant.merchant_category_code Merchant category code defined by
String 1..4 R
Appendix B - list of merchant
category code
original.participant.card_acceptor_id Card acceptor / terminal id /
String 1..8 R
wallet id
original.participant.card_acceptor_name Card acceptor name, tag 59. This
original.participant.card_acceptor_city Card acceptor city, tag 60. This
original.participant.card_acceptor_country Card acceptor country, tag 58. This
original.participant.card_postal_code Card postal code, tag 61. This field
String 1..10 C is conditional, required if
original.participant.card_language_preference Card language preference, tag 64
sub tag 01. This field is
String 1..2 C
conditional, required if presented
in QR message.
original.participant.card_name_alternate_language Card name alternate language, tag
String 1..25 C
in QR message.
original.participant.card_city_alternate_language Card city alternate language, tag
String 1..15 C
in QR message.
original.participant.card_payment_system_specific System payment specific is
String 1..99 O
addition info.
original.recipient_account Recipient account information, an
String R
id"
original.recipient.date_of_birth Date of birth of the recipient as in
String 1..25 O
ISO 8601 format
String 1..50 O
recipient
original.recipient.address.line2 Second line of the address of the
String 1..50 O
recipient
original.recipient.address.country Country of the sender as an ISO
String 1..2 R
alpha country code
75
original.additional_message Message a financial institution will
String 1..999 O associate to the transfer and may
display
String 1..25 R
consumer
original.order_info.additional_data_request Customer additional data request
indicator
String 1..3 O • "A" = Customer address
transaction
Array of Detail information format key,
object value
4 Appendix A – Data Protection

The data exchange between Service consumer and NAPAS will be protected by 2 levels of
encryption, including:
- Transport level: this is at the encrypting at transmission, using SSL protocol.

- Business message encryption: some sensitive data group in the business message will be
encrypted and signed in JWE/JWS format for security between NAPAS and terminal or
device where data is read. This level of encryption prevent the sensitive data can be seen
by middle servers during transmission.
4.1 Certificate Scheme Exchange

Napas and partners should exchange the certificates during on-boarding process before making
the service consuming.
Key information and terminology:
- OCE: Off-Card Entity - keys are used in entities servers.
76
- SD: Security Domain - keys are used by trusted applications in the terminal or device where
the sensitive data is read.
Summary about keys and algorithms:
- All asymmetric key sizes will be 2048-bit (RSA).

- All symmetric key sizes will be 128-bits (AES).
- Keys will be exchanged in X509 certificate format.
- Algorithms:
• RSA PKCS #1 v2.0 for content encryption.
• RSA PKCS #1 v1.5 with SHA256 for signature generation and verification.
4.1.1 Key/certificates are provided by NAPAS to Partners

Terminology Key/cert properties and algorithms Purpose
All Content 128 bit symmetric keys used for AES- Content encryption keys – keys used to encrypt
Encryption Key (CEK) GCM sensitive content, generate on every usage.
PK/CA.OCE.CERT Public RSA 2048-bit key in X.509 Root OCE CA certificate that issues/signs leaf
certificate OCE certificates. This is Napas root CA.
PK/SIG.OCE.CERT Public RSA 2048-bit key in X.509 Message signature verification key, leaf OCE
certificate certificate. SIG.OCE.CERT is signed by
SK/CA.OCE.CERT
PK/JWS.OCE.CERT Public RSA 2048-bit key and X.509 JWS signature verification key, leaf OCE
certificate certificate. JWS.OCE.CERT signed by
SK/CA.OCE.CERT
PK/JWE.OCE.CERT Private/Public RSA 2048-bit key and JWE encryption key, leaf OCE certificate.
X.509 certificate JWE.OCE.CERT signed by SK/CA.OCE.CERT
4.1.2 Key/certificates are provided by Partners to NAPAS

Terminology Key/cert properties and Purpose
algorithms
All Content Encryption 128 bit symmetric keys used for Content encryption keys – keys used to encrypt sensitive
Key (CEK) AES-GCM content, generate on every usage.
PK/CA.OCE.CERT Private/Public RSA 2048-bit key Root OCE CA certificate that issues/signs leaf OCE
in X.509 certificate certificates. This is partner root CA.
PK/SIG.OCE.CERT Public RSA 2048-bit key in Message signature verification key, leaf OCE certificate.
X.509 certificate SIG.OCE.CERT is signed by SK/CA.OCE.CERT
PK/CA.SD.CERT Public RSA 2048-bit key in Root SD CA key and certificate that issues/signs
X.509 certificate intermediate SD certificates. This is the Device Root
Key.
PK/JWS.SD.CERT Public RSA 2048-bit key in JWS signature verification key, leaf OCE certificate.
X.509 certificate JWS.SD.CERT signed by SK/CA.SD.CERT
PK/JWE.SD.CERT Private/Public RSA 2048-bit key JWE encryption key and leaf OCE certificate.
in X.509 certificate JWE.SD.CERT signed by SK/CA.SD.CERT
4.2 Message Signature

For client authentication and message integrity, every message transport to/from NAPAS APIs
must contain a message signature individually. The signature is placed in header.signature of
77
HTTP body request (for PUT/POST verb) or in header.signature in HTTP header property
named header (for GET/DELETE).
4.2.1 Client to NAPAS

- Client uses client’s private key which associated with PK/SIG.OCE.CERT to create message
signature.
• For POST/PUT/PATCH methods:
header.signature = RSAwithSHA256(JSON_minified(payload))
• For GET/DELETE methods:

header.signature = RSAwithSHA256(header.requestor.id + header.reference-id +
header.timestamp + header.operation)
- At server site, NAPAS will use client’s PK/SIG.OCE.CERT to verify the signature in the
requested message.
4.2.2 NAPAS to Client

- NAPAS uses NAPAS’s private key which associated with PK/SIG.OCE.CERT to create
message signature.
• For DELETE/GET/POST/PUT/PATCH methods:
header.signature = RSAwithSHA256(JSON_minified(result) + ”,” + JSON_minified(payload))
- At client site, client shall use NAPAS’s PK/SIG.OCE.CERT to verify the signature in the
response message.
4.3 Content Encryption

This sections will describe the detail of data groups will be encrypted in JWS/JWE standard.
These data groups are parts of API request or response message.
4.3.1 account.data.profile
This data is encrypted in JWE/JWS format (see Appendix B). Data contains the following fields
(in JSON format before encryption):
Field
type
Account type, currently supported values: PAN, RAW, TOKEN.
PAN: card primary account number
RAW: Specifies a deposit account or generic account number that is not a
type String 1..20 R PAN
TOKEN: digitized number of card/account by Napas Tokenization Service
Default value is PAN

pan String 1..19 R Primary account number of account type
iss String 4 C Account issuing date, in format MMYY. This field is conditional.
78
exp String 4 C Account expiration date, in format MMYY. This field is conditional.
cvv String 1..3 O Card verification code (for credit card), reserved
Account signature – Base64 encoding of account signature image data,
sig String 1..999 O
reserved
fid String 1..999 O Fingerprint id, reserved
aid String 1..999 O Account Authorization Id, reserved
pwd String 1..999 O Account password, reserved
name String 1..999 R Account name, reserved
address Object O Account billing address, optional
address.street1 String 1..999 R Billing street address
address.street2 String 1..999 O Billing street address
address.city String 1..999 R Billing city
address.state String 1..999 O Billing state
address.zip String 1..99 O Billing zip code
address.country String 1..3 R Billing country as ISO alpha country code
79
5 Appendix B – JWE/JWS standard
Sensitive data is secured by using JWE/JWS format from device or terminal where data is read.
This provide the end-to-end security solution which limit the risk of data is seen by any middle
entities during transmission.
From device to encrypt data to Napas:
- Create JWE data using Napas OCE JWE public key (JWE.OCE.CERT) with CEK generate
for every usage.
- Create JWS of JWE data using device JWS private key (which will be verified by device
JWS.SD.CERT).
From device to decrypt data from Napas:
- Verify JWS signature using Napas JWS public key (JWS.OCE.CERT).

- Decrypt JWE payload data using device JWE private key.
5.1 JWE Details

JWE Header
Tag Description
alg Cryptographic algorithm used to encrypt the Content Encryption Key (CEK)
Content encryption algorithm used to perform authenticated encryption on the Plaintext to produce the
enc
cipher text and the Authentication Tag
kid Key reference ID, merchant public key hash
JWE Payload
Tag Description
encrypted_key Contains the value BASE64URL (JWE Content Encrypted Key). The Content Encryption Key is
encrypted with the Public Key, provided to client during onboarding (JWE.SD.CERT)
Contain the value BASE64URL (JWE Initialization Vector). Initialization vector used in the
Iv
encryption algorithm
ciphertext Encrypted In-App payment payload (JSON object in JWE format)
tag Contains the value BASE64URL(JWE Authentication Tag). For integrity of cipher text.
5.2 JWS Details

JWS Header
alg: Cryptographic algorithm used to generate signature (e.g., RS256)
kid: Key reference ID: merchant public key hash. Optional
cty: Payload Content Type (e.g., JWE)
JWS Payload
80
JWE compact serialization contains the value BASE64URL(JWE).
JWS Signature
JWS Signature contains the value BASE64URL(Signature of (JWS header || ‘.’ || JWS
Payload)).
81
6 Appendix C - Reconciliation File Format.
6.1 Successful transaction file and processed transaction file in a
session
The detail file contains the successful transactions in a session created by Napas and sent to the
MO: MMDDYY_ZZZ_BBB_999999_X_TC_<ServiceCode>.dat
The detail file contains the processed transactions in a session created by Napas and sent to
the MO: MMDDYY_ZZZ_BBB_999999_X_XL_<ServiceCode >.dat
The file format consists of 03 parts:

- Header line (Header): describes the file header information.
- Detail lines (Detail): each transaction corresponds to a line in this file. Each transaction line
ends with a checksum field to verify the integrity of the data.
- Trailer line (Trailer): contains information such as the number of transactions in the file, the
file creator, creation date of file, checksum value of file.
After receiving the file, the MO has to check each line in the file and the line checksum value to
verify the integrity of the line, and check the file checksum value to verify the integrity of
the file.
6.1.1 Header line format (Header)
No Field Name Type Length Value Description
1. Record type Character 2 HR

Record type
HR = Header Record
2. Character 5 [REV]
Identification code of “Receiver bank”
Field identification
field
code
(Receiver – REV)
Receiver Bank Character 8

code
The receiver bank code must be same
with the bank code in filename
The code is right
indented and padded space in the left
if there is less than 08 characters
82
3. Character 6 [DATE]
Field identification Identification code of “Transaction
code date (DATE)” field
Transaction date Number 8
Transaction date of last transaction in

the reconcilation file
In ddMMyyyy format:
dd: Date
MM: Month yyyy: Year
6.1.2 Detail line format (Detail)

No Field Name Type Length Value Description Mapping Field APIs
1 Record type Character 2 DR Record type
DR = Detail Record
2. Field Character 5 [MTI] Identification code of MTI field
identification
code
Message Number 4 Message Type Indicator RRC<>119: MTI = 0210

Type Indicator RRC =119:
(MTI) - If Issuer send MTI =
0200 then Napas return
MTI = 0200.
- If Issuer send MTI =
MTI = 0210.
3. Field Character 4 [F2] Identification code of F2 field
identification
code
Primary Account Character 19 Card number is right indented and The PAN field in the
Number (F2) padding space in the left if there account.data.profile object.
is less than 19 characters

identification
code
Processing Code Number 6 Transaction processing code The TYPE tin the
(F3) account.data.profile object
If Type= “PAN” then value is

910020
83
If Type= “RAW” then value
is 912020
5. Field Character 5 [SVC] Identification code of Service

identification Code (SVC) field
code
Service Code Character 10 Service Code – specified by payment.type

(F62) NAPAS
6. Field Character 5 [TCC] Identification code of Transaction
identification Channel Code (TCC) field (F60)
code
Transaction Character 2 Identification code of Transaction payment.channel
Channel Code Channel field (F60)

identification
code
Transaction Number 12 Transaction amount is converted Amount
Amount (F4) in VND if the transaction
performed oversea.
It has 02 decimal digits, padding
left with zero if it’s value is less
than 12 digits
8. Field Character 5 [RTA] Field identification code Real

identification
code Transaction Amount
Real Transaction Number 12 Transaction amout is converted in RTA = F5 - Số tiền hoàn trả
Amount VND if the transaction performed
oversea.
Transaction Amount in VND

currency, with 02 decimal digits,
padding left with zero if it’s value
is less than 12 digits.
If transaction is successful and is
not reversed, then this amount is
equal to the transaction amount
(F4).
reversed, then this amount is zero.

reversed partialy, then this
amount is less than the
transaction amount (F4).
9. Field Character 5 [F49] Identification code of F49 field.

identification
code
84
Currency Number 3 The currency code with 03 currency
code(F49) numbers, padding left with zero if
it’s value is less than 03 digits.
identification
code
Settlement Number 12 02 decimal digits, padding left Amount

Amount (F5) with zero if it’s value is less than
12 digits

identification
code
Settlement Number 3 The currency code with 03 settlement_currency
currency code numbers, padding left with zero if
(F50) it’s value is less than 03 digits

identification
code
Settlement Number 8 This field format : nXXXXXXX Default is “1”

exchange rate
(F9) n : number of decimal
digits.
XXXXXXX : exchange rate
Fill zero if there is no value.

identification
code
Billing Amount Number 12 02 decimal digits, padding left

(F6) with zero if it’s value is less than
12 digits
14. Field Character 5 [RCA]

Identification code of Real
identification
Cardholder Amount field
code
Real Cardholder Number 12 02 decimal digits, padding left
Amount with zero if it’s value is less than
12 digits.
not reversed, then this amount is
equal to the transaction amount.
reversed, then this amount is zero.
reversed partialy, then this
amount is less than the
transaction amount
85
15. Field Character 5 [F51] Identification code of
identification
code F51 field
Cardholder Number 3 The currency code with 03

Billing currency numbers, padding left with zero if
code (F51) it’s value is less than 03 digits

identification
code
Cardholder billing Number 8 This field format : nXXXXXXX

conversion rate
(F10) n : number of decimal digits.
XXXXXXX : exchange rate
Fill with zero if there is no value.

identification
code
System Trace Number 6 payment.trace
Padding left with zero if there is
Audit
less than 06 digits
Number(F11)

identification
code
Local transaction Number 6 In HHmmss format Convert the transaction time

time (F12) to HHmmss format from:
HH : hour (24-hours format)
payment.transaction
mm : minute _local_date_time field
ss : second

identification
code
Local transaction Number 4 In MMdd format Convert the transaction date
date (F13) to MMdd format from:
MM : month
payment.transaction
dd : day of month _local_date_time field

identification
code
Settlement date Number 4 In MMdd format settlement_date

(F15)
MM : month
dd : day of month

identification
code
86
Merchant Number 4 Merchant type recipient.merchant_category_
category code code
(F18)
identification
code
Chế độ tại điểm Number 3 The entry mode at Point-of- Defaults is “000”
truy cập dịch vụ service
(F22) The code identifies how the PAN
and PIN is inputted at the Point-
of-service
identification
code
Number 2 The entry mode at Point-of- Defaults is “00”

service
Point-of-service
Entry Mode (F22) The code identifies how the PAN
and PIN is inputted at the Point-
of-service
24. Character 5 [F41] Identification code of F41 field
Field For ECOM service : filled with
identification merchant ID (numeric), padding
code left with zero if it’s value is less
than 8 characters
Card acceptor Character 8 participant.card_acceptor_id

terminal A unique code to identify a card
identification(F41 acceptor in acquirer bank system
)
25. Field Character 5 [ACQ]

Identification code of Acquiring
identification
institution code field (F32)
code
Acquiring Character 8 Acquirer identification code is participant.originating_institu
institution code registered in Napas tion_id
(F32)
Padding left with zero if it’s
value is less than 08 digits
26. Field Character 5 [ISS]
Issuer identification code (Issuer
identification
Identify)
code
Issuing Character 8 Issuer identification code was Napas will fill in

identification registered in Napas
code
It is right indented, padding left
with zero if it’s value is less than
08 digits.
87
27. Character 5 [MID] Identification code of card
Field acceptor identification code
identification field
code
(F42)
Character 15 The unique code identifies card

acceptor identification code in
POS transaction
For Ecom service, this field
record card acceptor
identification code (characters), if
it’s
Card acceptor
identification value is more than 15 numbers,
code (F42) only take the first 15 numbers
For IBFT service, this field record
Payment Intermediary
identification code
It is right indented, padding left
with zero if it’s value is less than
15 digits
28. Field Character 5 [BNB]

Identification code of F100
identification
(Beneficiary Identify) field
code
Beneficiary Character 8 participant.receiving_instituti

For IBFT, padding left with zero
identification on_id
if it’s value is less than 08 digits
code (F100)
identification
code
Source Account Character 28 Padding left with space if it’s The PAN field in the
Number(F102) value is less than 28 digits sender_account object

identification
code
Destination Character 28 The PAN field in the
Padding left with space if it’s
Card/Account recipient_account object
value is less than 28 digits
number(F103)
31. Field Character 10

[SVFI Identification code of ISS service
identification
SSNP] fee for NAPAS field
code
ISS Fee (service Number 12 Padding left with zero if it’s value Napas will fill in
fee of ISS for is less than 12 digits
NAPAS)
02 decimal digits.
Fill with zero if there is no value
88
32. Field Character 11 [IRFIS
Identification code of ISS
identification SACQ
interchange fee for ACQ field
code ]
ISS Fee Number 12 Padding left with zero if it’s value Napas will fill in
(interchange fee is less than 12 digits
of ISS for ACQ)
02 decimal digits,
33. Field Character 11 [IRFIS

Identification code of ISS
identification SBNB
interchange fee for BNB field
code ]
ISS Fee Number 12 Padding left with zero if it’s value Napas will fill in
(interchange fee is less than 12 digits
of ISS for BNB)
02 decimal digits,
34. Field Character 10 [SVFA

Identification code of ACQ
identification CQNP service fee for NAPAS field
code ]
Number 12 Padding left with zero if it’s

ISS Fee value is less than 12 digits
(interchange fee
02 decimal digits,
of ISS for BNB)
35. Field Character 11 [IRFA Identification code of ACQ

identification service fee for NAPAS field
code CQISS
]
ACQ Fee Number 12 Padding left with zero if it’s value Napas will fill in
(service fee of is less than 12 digits
ACQ for NAPAS 02 decimal digits,
36. Field Character 11 [IRFA Identification code of ACQ
identification interchange fee for BNB field
code CQBN
B]
ACQ Fee Number 12 Padding left with zero if it’s Napas will fill in
(interchange fee value is less than 12 digits
of ACQ for BNB)
02 decimal digits,
37. Field Character 10 [SVFB

Identification code of BNB
identification NBNP service fee for NAPAS field
code ]
89
BNB Fee Number 12 Padding left with zero if it’s value Napas will fill in
(service fee of is less than 12 digits
BNB for NAPAS
02 decimal digits,
38. Field Character 11 [IRFB Identification code of BNB
identification interchange fee for ISS field
code NBISS
]
BNB Fee Number 12 Padding left with zero if it’s value Napas will fill in
(interchange is less than 12 digits
fee of BNB for 02 decimal digits,
ISS Fill with zero if there is no value
39. Field Character 11 [IRFB Identification code of BNB

identification interchange fee for ACQ field
code NBAC
Q]
BNB Fee Number 12 Padding left with zero if it’s Napas will fill in
(interchange value is less than 12 digits
fee of BNB for 02 decimal digits,
ACQ Fill with zero if there is no value
40. Field Character 5 [F37] Identification code of F37 field.

identification
code For ECOM service :filled with
transaction code.
Retrieval Character 12 Transaction Retrieval Reference payment.payment_reference

Reference number number
(F37)
Padding left with space if it’s
alue is less than 12 digits

identification
code
Authorization Character 6 payment.authorization_code
Identification Authorization Number is
responded by Issuer Fill the
Response space if there is no value
(F38)
42. Field Character 5 [TRN] Identification code of F63 field

identification (Transaction Reference Number –
code
TRN)
90
Transaction Character 16 The transaction identification payment.reference
Reference number is generated by Napas
Number – TRN
(F63) when the transaction is processed
43. Field Character 5 [RRC] Identification code of

identification
code Reconcilation response
code field (RRC)
Reconciliation Number 4 Reconciliation Response Code is Napas will fill in

specified in the settlement process
Response for MO
Code Padding left with zero if it’s
value is less than 4 digits.
44. Field
[RSV1
identification Character 6 Reserve information field 1
]
code
Character 100 - For ECOM service: Noted that

this field to add and fill with full Combine the value of the 3
values using with merchants in fields below:
ECOM service.
+ From 1-32 (including 32 sender.first_name
characters) : filled with merchant
code (but from Field 48 of online sender.middle_name
message), padding right with sender.last_name
space if it is less than 32
characters. And space in the middle
Reserve
information 1 + From 33-52 (including 20
characters) : filled with
transaction code (but from Field
48 of online message), padding
right with space if it is less than
20 characters.
+ From 53-100 : not used, filled
with spaces.
- For the other services : filled
with spaces
45. Field Character 6 [RSV2 Reserve information field 2
identification ]
code
Reserve Character 100 At present, it is not used. Napas will fill in

information 2 Reserved for future, filled with
space characters
46. Field Character 6 [RSV3 Reserve information field 3

identification ]
code
91
Reserve Character 100 At present, it is not used. Napas will fill in
information field Reserved for future, filled with
3 space characters
47 Field Character 5 [CSR]
Identification code of
identification
Checksum field (CSR)
code
Checksum value Characte 32 To verify the integrity of data Napas will fill in
r line
Checksum is calculated using
MD5 hash
6.1.3 Trailer line format (Trailer)

1. Record type Character 2 TR Record type

TR = Trailer Record
2. Field Character 5 [NOT] Identification code of

identification code NOT (Number Of
Transactions) Field
Number Of Number 9 The number of

Transactions transaction lines in file
3. Field Character 5 [CRE] Identification code of Creator field

identification code
File creator Character 20 The user identification of the system which

exports the file
Padding left with zero if it’s value is less
than 20 digits
4. Field Character 6 [TIME] Identification code of Time field (TIME)

identification code
Creation time Number 6 The creation time on the system that exports
the file
in HHmmss format
mm : minute
ss : second
92
5. Field Character 6 [DATE] Identification code of file creation date field
identification code (DATE)
Creation date Number 8 The creation date is calculated same with

the system date that exports the file
In ddMMyyyy format MM : month dd
: day of month yyyy : year
6. Field Character 5 [CSF] Identification code of Checksum field (CSF)

identification code
Checksum value Number 32 To verify the integrity of the trailer line, to

check a summary of line on creation file
Checksum is calculated using MD5 hash
6.2 Detail line format (Detail)

The detail file contains the dispute transactions in a session created by the MO and sent to
Napas: MMDDYY_ZZZ_BBB_999999_X_SL_<ServiceCode>.dat
The file format consists of 03 parts:
- Header line: describes the file header information.
- Detail lines: each transaction corresponds to a line in this file. Each transaction line ends with
a checksum field to verify the integrity of the data.
- Trailer end: contains information such as the number of transactions in the file, the creator
file, file creation date, file checksum value.
After receiving the file, the Napas has to check each line in the file and the line checksum value
to verify the integrity of the line, and check the file checksum value to verify the integrity of the
file.
93
6.2.1 Header line format (Header)
Index Field name Type Length Value Description
1. Record type Character 2 HR Record type,

HR = Header Record
2. Field identification Character 5 [REV] Field identification code mã ngân hàng nhận
code (Receiver - REV)
Receiver Bank code Character 8 The receiver bank code must be same with the
bank code in filename
The code is right indented and padded space in
the left if there is less than 08
characters
3. Field identification Character 6 [DATE] Identification code of “Transaction date

code (DATE)” field
Transaction date Number 8 Transaction date of last transaction in the

reconcilation file In ddMMyyyy format:
dd: Date
MM: Month
yyyy: Year
6.2.2 Detail line format (Details)
No Field Name Type Length Value Description Mapping with APIs'field
Record type
1 Record type Character 2 DR
DR = Detail Record
Field
Identification code of MTI
identification Character 5 [MTI]
field
code
2 RRC<>119: MTI = 0210

Message
Type Indicator Number 4 Message Type Indicator RRC =119:
(MTI)
MTI = 0200.
94
MTI = 0210.
Field
identification Character 4 [F2]
field
code
3 The PAN field in the
account.data.profile object.
Card number is right
Primary
indented and padding
Account Character 19
space in the left if there is
Number (F2)
less than 19 characters
Field
field
code
Field Type in the
account.data.profile
4
- If Type=PAN then value
Processing Transaction
Number 6 is 910020
Code (F3) processingcode
- If Type= RAW then
value is 912020
Field
identification Character 5 [SVC]
Service Code (SVC) field
5 code
Service Service Code – specified
Character 10
Code (F62) by NAPAS payment.type
Field Identification code of
identification Character 5 [TCC] Transaction Channel Code
code (TCC) field (F60)
6
Transaction
Character 2 Transaction Channel field
Channel Code
(F60) payment.channel
Field
field
code
Transaction amount is
converted in VND if the
7
transaction performed
Transaction
Number 12 oversea. It has 02 decimal
Amount (F4)
digits, padding left with
zero if it’s value is less
than 12 digits amount
Field Identification code of of
8 identification Character 5 [RTA] Real Transaction Amount
code field
95
Transaction amount is
converted in VND if the
transaction performed
oversea. Transaction
Amount in VND currency,
with 02 decimal digits,
padding left with zero if
it’s value is less than 12
digits. If transaction is
Real
successful and is not
Transaction Number 12
reversed, then this amount
Amount
is equal to the transaction
amount (F4). If transaction
is successful and is
reversed, then this amount
is zero. If transaction is
successful and is reversed
partialy, then this amount
is less than the transaction
amount (F4).
Field
field.
code
9 The currency code with 03
Currency numbers, padding left with
Number 3
code (F49) zero if it’s value is less
than 03 digits. currency
Field
field
code
10
02 decimal digits, padding
Settlement
Number 12 left with zero if it’s value
Amount (F5)
is less than 12 digits
settlement_amount
Field
field
code
11 The currency code with 03
Settlement
numbers, padding left with
currency code Number 3
(F50)
than 03 digits. settlement_currency
Field
field
code
This field format :
12 nXXXXXXX n : number
Settlement
of decimal digits.
conversion rate Number 8 F9
XXXXXXX : exchange
(F9)
rate Fill zero if there is no
value. Default is “1”
Field
field
code
13
Cardholder 02 decimal digits, padding
Billing Number 12 left with zero if it’s value
Amount (F6) is less than 12 digits
96
Field
Identification code of Real
identification Character 5 [RCA]
Cardholder Amount field
code
02 decimal digits, padding
left with zero if it’s value
is less than 12 digits. If
transaction is successful
and is not reversed, then
this amount is equal to the
14
Real transaction amount. If
Cardholder Number 12 transaction is successful
Amount and is reversed, then this
amount is zero. If
transaction is successful
and is reversed partialy,
then this amount is less
than the transaction
amount.
Field
15 identification Character 5 [F51]
field
code
The currency code with 03
Cardholder numbers, padding left with
Number 3
Billing (F51) zero if it’s value is less
than 03 digits.
Field
field
code
This field format :
nXXXXXXX
Cardholder n : number of decimal
Billing digits.
Number 8
Conversion XXXXXXX : exchange
Rate (F10) rate
Fill with zero if there is no
value
Field
field
code
System
Trace Padding left with zero if
Number 6
Audit Number there is less than 06 digits
(F11) payment.trace
Field
field
code
In HHmmss format
18 Convert the transaction time
Local HH : hour (24-hours
transaction Number 6 format) to HHmmss format from:
time (F12) mm : minute payment.transaction
ss : second _local_date_time
field
Field
field
code
97
Convert the transaction date
Local In MMdd format to MMdd format from:
transaction Number 4 MM : month payment.transaction
date (F13) dd : day of month _local_date_time
field
Field
field
code
20
In MMdd format
Settlement
Number 4 MM : month settlement_date
date (F15)
dd : day of month
Field
field
code
21
Merchant
recipient.merchant_category
Category Code Number 4 Merchant type
_code
(F18)
Field
field
code
The entry mode at Point-
22 of-service
Point-of-
The code identifies how
service Entry Number 3 Default is “000”
the PAN and PIN is
Mode (F22)
inputted at the Point-of-
service
Field
field
code
Point-of-
service The condition code at
Number 2 Default is “00”
Condition Point-of-service
Code (F25)
Field
field
code
A unique code to identify a

card acceptor in
acquirer bank system.
24 Card Acceptor
Terminal For ECOM service : filled
Character 8 participant.card_acceptor_id
Identification with merchant ID
(F41) (characters with numeric
format), padding left with
than 8 characters
98
identification Character 5 [ACQ] Acquiring institution code
code field (F32)
Acquirer identification
25
code is registered in
Acquiring
Napas participant.originating_instit
Institution Character 8
Padding left with zero if ution_id
Code (F32)
it’s value is less than 08
digits
Field
Issuer identification code
identification Character 5 [ISS]
(Issuer Identify)
code
Issuer identification code

26
was registered in Napas
Character 8 It is right indented,padding
Issuing left with zero if it’s value
Identification is less than 08 digits.
Code
Identification code of card
Field
acceptor identification
identification Character 5 [MID]
code field
code
(F42)
The unique code identifies
a card acceptor in POS
transactions.
For Ecom service, this
field record merchant
identifciation code
27 (character), if it’s value is
more than 15 numbers,
Character 15 only take the first 15
numbers.
For IBFT service, this field
record Payment
Intermediary code It is
right indented, padding left
Card Acceptor with zero if
Identification it’s value is less than 15
Code digits
identification Character 5 [BNB] F100 (Beneficiary
code Identify) field
28
For IBFT, padding left
Beneficiary Character 8 with zero if it’s value is
Identification less than 08 digits participant.receiving_institu
Code (F100) tion_id
Field
field
code
29 Source
Padding left with space if
Account
Character 28 it’s value is less than 28
Number The PAN field in the
digits
(F102) sender_account object
99
Field
field
code
30
Destination Padding left with space if
Card/Account Character 28 it’s value is less than 28
number digits The PAN field in the
(F103) recipient_account object.
Field field.
identification Character 5 [F37] For ECOM service :
code filled with transaction
code.
31
Reference number
transaction for
Retrieval Character 12 reconciliaction
Reference Padding left with if it has
Number (F37) less than characters payment.payment_reference
Field
field
code
32 Authorization Authorization Number is
Identification responded from Issuer.
Character 6
Response Fill space if there is no
(F38) value payment.authorization_code
Field
field (Transaction
identification Character 5 [TRN]
Reference Number –
code
TRN)
33 The transaction
Transaction identification number is
Reference Character 16 generated by Napas
Number – when the transaction is
TRN (F63) processed payment.reference
identification Character 5 [RRC] Reconcilation response
code code field (RRC)
Reconciliation Response
34
Code is specified in the
settlement process for MO.
Number 4
Reconciliation Padding left with zero if
Response it’s value is less than 4
Code digits.
Field
Reserve information field
35 identification Character 6 [RSV1]
1
code
100
- For ECOM service :
Noted that this field to add
and fill with full
values using with
merchants in ECOM
service.
+ From 1-32 (including 32
characters) : filled with
merchant code (but from
Field 48 of online
message), padding right
with space if it is less than
Character 100 32 characters.
+ From 33-52 (including
20 characters) : filled with
transaction code (but from
Field 48 of online
message), padding right
with space if it is less than Combine the value of the 3
20 characters. fields below:
+ From 53-100 : not used,
filled with spaces. sender.first_name
- For the other services :
sender.middle_name
filled with spaces
sender.last_name
Reserve
information 1 And space in the middle
Field
identification Character 6 [RSV2]
2
code
36 At present, it is not used.

Reserved for future, filled
Character 100
with space
Reserve characters
information 2
Field
identification Character 6 [RSV3]
3
code
37 At present, it is not used.
Reserved for future, filled
Character 100
with space
Reserve characters
information 3
Field
identification Character 5 [CSR]
Checksum field (CSR)
code
38 To verify the integrity of
data line
Character 32
Checksum Checksum is calculated
value using MD5 hash
101
6.2.3 Trailer line format (Trailer)
1 Record type Character 2 TR Record type,

TR = Trailer Record
2 Field identification Character 5 [NOT] Identification code of NOT (Number Of

code Transactions) Field
Number Of Number 9 The number of transaction lines in file

Transactions
3 Field identification Character 5 [CRE] Field identification code người tạo file
code (Creater - CRE)
File creator Character 20 The user identification of the system which

exports the file
Padding left with zero if it’s value is less
than 20 digits
4 Field identification Character 6 [TIME] Field identification code giờ tạo file (TIME)
code
Creation time Number 6 The creation time on the system

that exports the file
in HHmmss format
mm : minute
ss : second
5 Field identification Character 6 [DATE] Identification code of file creation date field
code (DATE)
Creation date Number 8 The creation date is calculated same with

the system date that exports the file
In ddMMyyyy format
MM : month
dd : day of month
yyyy : year
6 Field identification Character 5 [CSF] Identification code of Checksum Field
code (CSF)
Checksum value Character 32 To verify the integrity of the trailer line, to

check a summary of line on creation file
Checksum is calculated using MD5 hash
102

Napas - TechSpec For QR Payment - API - Bank - v0.8

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Napas - TechSpec For QR Payment - API - Bank - v0.8

Uploaded by

Copyright:

Available Formats

API TECHNICAL SPECIFICATION

This document also includes both incoming and

0.8 14-Oct-2021 Bui Quang Minh Do Thi Ha Update response code.

1.4 Terms and abbreviation

STT Abbreviation Description

1.5 How to use this document

All API’s fields are described by their attributes:

- Field Name: Name of field as used to form the system call.

- O: Optional – data element is optional

2.1.1 For domestic QR Code the flow lookup QR is required

2.1.2 For cross border QR Code the flow lookup QR is required

2.2 Customer uses application of Originating Institution to make

Note: Originating Institution may be Issuing bank or Payment Intermediary. Receiving

2.2.1 Domestic QR: the flow lookup QR is required

2.2.2 Cross border QR: the flow lookup QR is required

Step 1: Customer confirms payment on the mobile application

2.3.2 For cross border

From step 1 to step 8 see at session 2.2.1

From step 1 to step 10 see at session 2.2.2

3.1 API General Contract

Authentication Mutual SSL / Digital Signature

Security Method JWE/JWS (if applicable)

3.1.2 API Request

Field name Field type Length Mandatory Description

Assigned by sending bank or gateway to uniquely identify

(2) GET Method

Request HTTP header custom fields:

3.1.3 API Response

Field name Field type Length Mandatory Description

header.requested-by.requestor.name String O Name of registered service consumer

Reference id of request. This value should be

FATAL – Error that causes system to crash,

WARNING – Error that might lead to severe error

3.2.1 Account Services

Operation URL {NAPAS_API_BASE_URL}/{partner_id}/merchant/transaction/inquiry

HTTP Method POST

Security Method JWE/JWS

Request Payload Fields detail

For ITMX QR, you must follow the rules of ITMX:

trace String 1..6 R System trace audit number of original transaction

At the beginning of the organization issue the VN

O At the beginning of the ESB call request to ITMX,

The first ITMX call request camt.005 to ESB needs

original_originating_institution String 1..8 The organization sending the original payment

Encrypted this information

Encrypted this information

Response HTTP Header

Response Payload Fields detail

Field name Field type Length Mandatory Description

For ITMX QR, you must follow the rules of

id_orig_payment String 1..35 O The EndToEndId of the parent transaction

orig_resp_datetime String 1..25 O Date and time of the original payment

error_desc String 1..100 O Error description request payment enquiry

orig_amount Number 1..12 O Amount of original payment transaction

3.2.2 QR Switch Services

Ngân hàng Thanh toán / Trung gian

Ngân hàng Phát hành / 7 6

Section 1 – Domestic QRcode high level model

Vietnam s customer Foreign merchant QR

Foreign s Acquiring Bank

VietNam s Settlement Bank Foreign s Settlement Bank

Section 2 – Vietnam’s cutomer scan QR code at Merchant’s foreign store high