API TECHNICAL SPECIFICATION

24/7 IBFT TRANSACTIONS INQUIRY

- FOR 24/7 IBFT TRANSACTIONS INQUIRY -

Version 0.3

12/2022

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 ................................................................................................ 5
2 Services and Use Cases ........................................................................................................... 7
2.1 Originating Institution calls API transactions inquiry to Napas ...................................... 7
2.1.1 24/7 IBFT transaction inquiry flow .......................................................................... 7
3 Technical Specification ........................................................................................................... 7
3.1 API General Contract ....................................................................................................... 7
3.1.1 General Protocol Description .................................................................................... 7
3.1.2 API Request .............................................................................................................. 9
3.1.3 API Response .......................................................................................................... 10
3.1.4 API Response Codes ............................................................................................... 15
3.2 Business Message Format .............................................................................................. 18
3.2.1 24/7 IBFT transactions inquiry service ................................................................... 18
3.2.1 System health check ................................................................................................ 22
4 Security Access Control ........................................................................................................ 24
4.1.1 The OAuth 2.0 Authorization ................................................................................. 24
4.1.2 SSL Protocol ........................................................................................................... 24
4.1.3 General Protocol Description .................................................................................. 24
4.1.4 API Request / Response .......................................................................................... 24
4.1.5 API Response Code ................................................................................................ 25
4.1.6 Signature ................................................................................................................. 25
5 Appendix A – Data Protection............................................................................................... 26
5.1 Certificate Scheme Exchange......................................................................................... 26
5.1.1 Key/certificates are provided by NAPAS to Partners ............................................. 26
5.1.2 Key/certificates are provided by Partners to NAPAS ............................................. 27
5.2 Message Signature.......................................................................................................... 27
5.2.1 Client to NAPAS..................................................................................................... 27
5.2.2 NAPAS to Client..................................................................................................... 28

2
6 Appendix B – JWE/JWS standard ......................................................................................... 29
6.1 JWE Details .................................................................................................................... 29
6.2 JWS Details .................................................................................................................... 29

3
 Document Control

Versio Updated Updated by Reviewed by Description

n date
0.1 08-Dec-2022 Nguyen Hoang Nguyen Initial version for 24/7 IBFT transactions
Nam Hoang Nam inquiry

This document also includes both incoming

and outgoing message format.
0.2 23-Dec-2022 Ly Dinh Quang Nguyen Add Authentication Protocol in section 4
Nguyen Hoang Hoang Nam Update section 3 with protocol flow
Nam
0.3 12-Jan-2023 Pham Duc Nguyen Update message authentication
Nhon Hoang Nam
0.4 08-Feb-2023 Nguyen Hoang Nguyen Update Card_No and Account_No fileds
Nam Hoang Nam requiring to be encrypted in request and
response messages

4
1 Introduction

This document defines technical specifications for 24/7 IBFT transactions inquiry that can be
consumed by member banks who need to inquire transactions conducted via NAPAS 24/7 IBFT
service. It describes message structure and format with detailed transmission manners between
NAPAS and member banks.
1.1 Audience
The audience of this document are NAPAS’ member banks who register and consume 24/7 IBFT
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 member banks.
1.3 Support
For any assistance or information pertaining to service(s), 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 Member bank who sends inquiry message to inquire 24/7 IBFT transaction
Institution status.

2 Receiving Member bank who receive inquiry message to inquire 24/7 IBFT transaction
Institution status.
3 Issuing Bank The financial institution that provides accounts or/and issue card to customer.
4 Acquiring The financial institution that provides accounts or/and processes card
Bank transactions.

1.5 How to use this document

All technical APIs described in this document focus on technical specifications and functions of
transactions inquiry via NAPAS’ 24/7 IBFT service.
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 detailed description.

5
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 transactions inquiry to Napas
2.1.1 24/7 IBFT transaction inquiry flow

Step 1: Originating Institution creates and sends 24/7 IBFT transactions inquiry request to Napas
Step 2: Napas check and look up transaction information
Step 3: Napas sends responding 24/7 IBFT transactions inquiry to Origination Institution
3 Technical Specification
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

7
Protocol Flow:

(A)
Client Authentication

(B)
Access Token

(C)
Access Token

(D)
Protected Resource

A - Partner sends request to get an access_token to Authorization Server.

B - Authorization Server authorizes Partner and returns an access_token.
C - Partner captures the returned access_token and uses it to access APIs in Resource Server by
passing this Bearer token to HTTP Header of each request.
Authorization: Bearer access_token_value
D - Resource Server serves functional APIs to Partner.
(Detail of authentication will be described in section 4)
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}/api/{sub_system}/{version}/{resource/operati
on}/{id}

Example:
https://api.napas.com.vn/api/ibftis/v1/partners/45e04108-a022-11e4-89d3-
123b93faecba/
Authentication Token-based Authentication/Digital Signature
Transmission HTTPS
Messaging Restful-JSON
Security Method JWE/JWS (if applicable)

8
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 partners, 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 reasons, 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 with 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.
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:

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 Lengt Mandator

Field name Description
type h y
header Object R API request header data group

9
header.requestor Object R Service consumer data group.
header.requestor.id String 10 R ID of registered service consumer in NAPAS
system.
header.requestor.na String 40 O Name of registered service consumer.
me
header.reference-id String 40 R Reference id of request. This value should be
generated and maintained in service consumer
system.
header.timestamp String O Timestamp of the request.
header.operation String 40 R The formal operation name of the request. This
value must be matched with operation
definition from NAPAS.
header.signature String 1000 O Signature of the request message, details of
generating signature are described in Appendix
A – Data Protection, part 3.1 Message
Signature.
Header.token String 300 R Bearer access_token_value
payload Object R API request payload data group. This can be
any business message which will be defined
in section 3.2 Business Message Format.

(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
Field name Mandatory Description
type
The JSON string which represents the ‘header’
header String R
object which described in section 3.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

The response HTTP body is constructed by 3 parts:

10
- 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.

11
12
 Field
Field name Length Mandatory Description
type
header Object R API request header data group
header.operation-id String 40 R The id of processed operation
header.operation-name String 40 O Name of processed operation
Contains the original requested
header.requeted-by Object R
header data group
header.requeted-
Object R Service consumer data group
by.requestor
header.requeted- ID of registered service consumer in
String 10 R
by.requestor.id NAPAS system
header.requeted- Name of registered service
String 40 O
by.requestor.name consumer
Reference id of request. This value
header.requeted-
String 40 R should be generated and maintained
by.reference-id
in service consumer system
Timestamp of the original request
ISO8601: yyyy-MM-
header.requeted-
String 35 O dd’T’hh:mm:ss.SSS+hh:mm
by.timestamp
Eg: 2019-03-
25T10:32:24.634+07:00
The formal operation name of the
header.requeted- request. This value must be matched
String 40 R
by.operation with operation definition from
NAPAS.
header.requeted-
String 1000 O Signature of the original request.
by.signature
Timestamp of the response message
ISO8601: yyyy-MM-
header.timestamp String 35 O dd’T’hh:mm:ss.SSS+hh:mm
Eg: 2019-03-
25T10:32:24.634+07:00
header.signature String 1000 O Signature of the response message
Header.token String 300 R Bearer access_token_value
result Object R Operation result data group
Result reference id. This value can
result.id String 40 R be used for querying status detail
api
result.code String 10 O Application specific error code
result.message String 200 O Application specific error message
result.description String 400 O Error description. Optional
Error Severity. Optional
Must be one of:
result.severity String 200 O
FATAL – Error that causes system
to crash, resulting in data loss or

13
 corruption or system not responsive.
ex) Out of Memory, Out of Disk.
Alerts must be generated
immediately

ERROR – Error that might cause

data loss or corruption or system not
responsive, if not fixed soon.
ex) Database connection error.
Alerts must be generated if the issue
persists for a given period.
Immediate action must be taken to
fix it.

WARNING – Error that might lead

to severe error if not fixed.
ex) ClassCastException
Fully qualified resource identifier
result.href String 40 O
for the error. Optional
Contains the response business
message object. This can be any
payload Object O business message which will be
defined in section 2.2 Business
Message Format

14
 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 does not exist
400.12 Invalid transaction
400.13 Invalid amount
400.14 Invalid Card number
404.15 No such Issuer
15
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
406.06 Transaction 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

16
transaction

17
Other errors
Code Description
400 Invalid JSON Request
401 Unauthorized
401 Account Inactive
403 Account Over Queries Per Second Limit
403 Account Over Rate Limit
403 Rate Limit Exceeded
504 Gateway Timeout
3.2 Business Message Format
This section describes business message formats 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
following API General Contract.
3.2.1 24/7 IBFT transactions inquiry service
NAPAS 24/7 IBFT transactions inquiry service provide the API to client to inquire transactions
information that processed by NAPAS via 24/7 IBFT service. This service receives request from
client and get transaction information from NAPAS internal processing system and throught
participants (member banks). For the first implementing phase, this service gets transaction from
NAPAS internal processing system.

NAPAS_API_BASE https://<host>:<port>/api/ibftis/v1/
_URL
Create Transaction Inquiry
This API is provided by NAPAS to Originating Institutions for querying transaction
information in case of unclear failure or timeout. Napas will get information from internal
processing system and/or routing transaction inquiry request to corresponding receiving
institution through its payment network.

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

}

HTTP Method POST

Authentication Token-based Authentication/Digital Signature

Protocol REST-JSON

Security Method JWE/JWS

header.operation IBFT_TRANSACTION_INQUIRY

Request Payload Fields detail

18
# Field Lengt Mandator Description
Field name
type h y
QUERY_TYP Inquiry type
String an-4 M
E - TVCK: IBFT 24/7 transaction inquiry
M Originating institution ID
SENDER_ID String n-6

NAPAS service that proceeded original

transaction:
SERVICE String
an-6 M - ACH : ACH service
- IBFT: IBFT service
M Acquiring member bank ID (F32)
ACQ_ID String n-6

O Benificial member bank ID

BEN_ID String n-6

From account number/card number of original

an200 transaction (F2). If not empty then must be
CARD_NO O
0 encrypted (Refer to Appendix A for detailed
data protection)
To account number/card number of original
transaction(F103). Set to be empty if having
TO_ACCOUN an200 no info. If not empty then must be encrypted
O
T 0 (Refer to Appendix A for detailed data
protection)
From account number of original transaction
FROM_ACCO an200 (F102). Set to be empty if having no info. If
O not empty then must be encrypted (Refer to
UNT 0
Appendix A for detailed data protection)

LOCAL_DAT M Transaction date of original transaction with

String n-10 format (dd/mm/yyyy) (F13)
E
LOCAL_TIM Numb M Transaction time of original transaction (F12)
n-6
E er
O Transaction amount of original
AMOUNT String n-12 transaction(F4)
M Trace number of original transaction (F11)
TRACE_NO n-6

M Terminal ID in original transaction (F41)

TERMID String an-8

19
 Request Code:
REQUEST_C M
String n-3 ▪ 101: inquirie transaction status
ODE

C If SERVICE is “ACH” then originating

RESERVE_1 String an-200 institution must fill in message id of original
transaction
O For reservation
RESERVE_2 an-200

O For reservation
RESERVE_3 an-200

Response HTTP Header

HTTP Header: HTTP/1.1 200 OK

Content-Type application/json
Location A complete URL to check the status of the request

Response Payload Fields detail

Field name Field type Length Mandatory Description

Inquiry type
QUERY_TYPE an-4 M
- TVCK: IBFT 24/7 transaction
inquiry
SENDER_ID n-6 M Originating institution ID

NAPAS service that proceeded

original transaction:
SERVICE
an-6 M - ACH : ACH service
- IBFT: IBFT service
ACQ_ID n-6 M Acquiring member bank ID (F32)

BEN_ID n-6 O Benificial member bank ID

From account number/card number

of original transaction (F2). If not
CARD_NO an2000 O empty then must be encrypted (Refer
to Appendix A for detailed data
protection)

20
 Field name Field type Length Mandatory Description
To account number/card number of
original transaction(F103). Set to be
empty if having no info. If not empty
TO_ACCOUNT an2000 O
then must be encrypted (Refer to
Appendix A for detailed data
protection)
From account number of original
transaction (F102). Set to be empty
if having no info. If not empty then
FROM_ACCOUNT an2000 O
must be encrypted (Refer to
Appendix A for detailed data
protection)
Transaction date of original
LOCAL_DATE n-10 M transaction with format
(dd/mm/yyyy) (F13)
M Transaction time of original
LOCAL_TIME n-6
transaction (F12)
M Transaction amount of original
AMOUNT n-12 transaction(F4)

M Trace number of original transaction

TRACE_NO n-6
(F11)
M Terminal ID in original transaction
TERMID an-8
(F41)
Request Code:
REQUEST_CODE n-3 M
▪ 101: inquirie transaction
status
Reference Code. Source of
REF_CODE int transaction status verification
▪ 1: From NAPAS
Responding code of original
RESPCODE n-2
transaction
Status of inquiry transaction

- 1: Waiting for settlement

- 2: No settlement
STATUS n-2 - 3: Not yet defined settlement
status
- 4: Be settled
- 5: Transaction not found
- 6: Wrong format or missed

21
 Field name Field type Length Mandatory Description
inquiry information

O If SERVICE is “ACH” then

REVERSE_1 an200 originating institution must fill in
message id of original transaction
O For reservation
REVERSE_2 an200

O For reservation
REVERSE_3 an200

Processing code of original

transaction

- Inquiry: 43xxxx
PROC_CODE n-6 C
- Transfer: 91xxxx

Only return information if

transaction found.

3.2.1 System health check

This set of APIs provide the NAPAS system information, with current usage is system health
check.

NAPAS_API_BASE_URL https://<napas_address>:<port>/api/ibftis/v1/systems

(1) NAPAS system health status

This function provides the current health status of NAPAS system. Partner uses the following
information to integrate with NAPAS server:

Operation URL {NAPAS_API_BASE_URL}/status

HTTP Method GET

Authentication N/A

Protocol REST-JSON

Security Method N/A

header.operation SYSTEMS_STATUS

Request Payload Fields detail

22
* This operation does not require any detailed information in HTTP body. However, for
HTTP method GET, Napas server still requires the custom HTTP header tab “header” as
described in section 2.1.2.(2) GET Method.
Response Payload Fields detail
* This operation does not return any property in body payload.

HTTP Header: HTTP/1.1 200 OK

Content-Type application/json
Location A complete URL to check the status of the request

23
4 Security Access Control
4.1.1 The OAuth 2.0 Authorization
OAuth 2 is an authorization framework that enables applications to obtain limited access to user
accounts on an HTTP service, such as Facebook, Google, GitHub... It works by delegating user
authentication to the service that hosts the user account and authorizing third-party applications
to access the user account. OAuth 2 provides authorization flows for web and desktop
applications, and mobile devices.
4.1.2 SSL Protocol
The communication between Partner and Napas system uses HTTPS connection with TLS1.2
protocol, so that data will be securely encrypted during transmission.
4.1.3 General Protocol Description

URL {NAPAS_API_BASE_URL}/api/oauth/token

Method POST
Content-Type application/json
Description Token is unique and valid for 5 minutes
4.1.4 API Request / Response
Field Lengt Mandator
Field name Description
type h y
Request
grant_type String 40 R Default value is “password”
client_id String 40 R Client Information Id that given by Napas
client_secret String 40 R Client Information Secret that given by Napas
username String 100 R Username Information that given by Napas
password String 100 R Password Information that given by Napas
Signature String 9999 R Sign all input values ordered by field name in
ascending alpha beta
Response
result String 50 R Return “SUCCESS” if there is no system error,
“ERROR” otherwise
ErrCode String 50 O Error code responds if and error occurs
ErrDesc String 250 O Error description responds if and error occurs
access_token String 250 O Access Token that given by Napas to access the
protected resource
token_type String 15 O “bearer” value is returned

24
refresh_token String 250 O Refresh Token that given by Napas to refresh
the access token.
expires_in String 10 O Access Token lifetime in seconds. Default is
300
scope String 50 O “read write trust” default
Signature String 9999 Y Sign all input values ordered by field name in
ascending alpha beta

4.1.5 API Response Code

ErrCode ErrDesc

PENDING The operation is currently in progress or pending processing

FAILURE The operation was declined or rejected by the gateway, acquirer or issuer

UNKNOWN The result of the operation is unknown

INVALID_REQUEST ${Filed Name} exceeds the max length

${Filed Name} wrong formats

Signature could not be verified

Request API Over Quota Limit

Username or password inactive

Username or password is incorrect

${Filed Name}is null

4.1.6 Signature
+ Napas prepares 1 key pair private, public key (RSA 2048 bit) and send public key to Merchant.
+ Merchant prepares 1 key pair private, public key (RSA 2048 bit) and send public key to Napas.
+ Step 1: Merchant makes a request, sign all input values with merchant’s private key.
+ Step 2: Napas receives the request information, checks the Signature value using the
merchant’s public key.
+ Step 3: Napas processes and sign the response with Napas’ private key.
+ Step 4: Merchant receives the response and checks it with Napas’ public key.

25
5 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 HTTPS connection with
TLSv1.2 or TLSv1.3 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 prevents the sensitive data can be seen
by middle servers during transmission.

5.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.

- 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 256-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.

5.1.1 Key/certificates are provided by NAPAS to Partners

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

26
PK/JWS.OCE.CERT Public RSA 2048-bit key and JWS signature verification key and
X.509 certificate leaf OCE certificate. JWS.OCE.CERT
signed by SK/CA.OCE.CERT
PK/JWE.OCE.CERT Private/Public RSA 2048-bit JWE encryption key and leaf OCE
key and X.509 certificate certificate. JWE.OCE.CERT signed
by SK/CA.OCE.CERT
5.1.2 Key/certificates are provided by Partners to NAPAS
Terminology Key/cert properties Purpose
and algorithms
All Content Encryption 256-bit symmetric keys Content encryption keys – keys used to
Key (CEK) used for AES-GCM encrypt sensitive content, generate on
every usage.
PK/CA.OCE.CERT Private/Public RSA Root OCE CA certificate that issues/signs
2048-bit key and X.509 leaf OCE certificates. This is partner root
certificate CA.
PK/SIG.OCE.CERT Public RSA 2048-bit Message signature verification key and
key and X.509 leaf OCE certificate. SIG.OCE.CERT is
certificate signed by SK/CA.OCE.CERT
PK/CA.SD.CERT Public RSA 2048-bit Root SD CA key and certificate that
key and X.509 issues/signs intermediate SD certificates.
certificate This is the Device Root Key.
PK/JWS.SD.CERT Public RSA 2048-bit JWS signature verification key and leaf
key and X.509 OCE certificate. JWS.SD.CERT signed by
certificate SK/CA.SD.CERT
PK/JWE.SD.CERT Private/Public RSA JWE encryption key and leaf OCE
2048-bit key and X.509 certificate. JWE.SD.CERT signed by
certificate SK/CA.SD.CERT
5.2 Message Signature
For client authentication and message integrity, every message transported to/from NAPAS APIs
must contain a message signature individually. The signature is placed in header.signature of
HTTP body request (for PUT/POST verb) or in header.signature in HTTP header property
named header (for GET/DELETE).
5.2.1 Client to NAPAS

- Client uses client’s private key which associated with SIG.OCE.CERT to create message
signature.
• For POST/PUT methods:

header.signature = RSAwithSHA256(JSON_minified(payload))

• For GET/DELETE methods:

27
header.signature = RSAwithSHA256(header.requestor.id + header.reference-id +
header.timestamp + header.operation)

- At server site, NAPAS will use client’s SIG.OCE.CERT to verify the signature in the
requested message.

5.2.2 NAPAS to Client

- NAPAS uses NAPAS’s private key which associated with SIG.OCE.CERT to create
message signature.
• For DELETE/GET/POST/PUT methods:

header.signature = RSAwithSHA256JSON_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.

28
6 Appendix B – JWE/JWS standard
Sensitive data is secured by using JWE/JWS format from device or terminal where data is read.
This provides the end-to-end security solution which limits 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
generated 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.

6.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
enc
to produce the 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)
Contains the value BASE64URL (JWE Initialization Vector). Initialization vector
Iv
used in the encryption algorithm
ciphertext Encrypted In-App payment payload (JSON object in JWE format)
Contains the value BASE64URL(JWE Authentication Tag). For integrity of cipher
tag
text.
6.2 JWS Details
JWS Header
alg: Cryptographic algorithm used to generate signature (e.g., RS512)
kid: Key reference ID: merchant public key hash. Optional
cty: Payload Content Type (e.g., JWE)

29
JWS Payload
JWE compact serialization contains the value BASE64URL(JWE).
JWS Signature
JWS Signature contains the value BASE64URL(Signature of (JWS header || ‘.’ || JWS Payload)).

30