NAPAS Payment Gateway

Merchant Integration Specification

Version 2.2

Hanoi 06-2016

NAPASMerchantIntegrationSpecification_2.2 page 1/32

 Index
I. Overview ............................................................................. 3
i. Document purpose ....................................................................................... 3
ii. System overview ........................................................................................... 3
iii. System glossary ............................................................................................ 3
II. Solution Feature .................................................................. 4
i. Connection model ......................................................................................... 4
ii. Connection prototype .................................................................................. 4
iii. Function support ............................................................................................ 5
III. Transaction flow ............................................................ 6
i. Transaction flow ............................................................................................. 6
IV. Transferred Data Definition ................................................. 8
i. Redirect Request from Merchant to NAPAS ........................................ 8
ii. Redirect Response from NAPAS to Merchant ....................................11
iii. Field values description............................................................................. 14
iv. Checksum Calculation ............................................................................... 15
V. Data Security .................................................................... 16
i. Security channel .......................................................................................... 16
ii. One time Password authorization ......................................................... 16
iii. Transaction rules ......................................................................................... 16
VI. Integrate and Implementation .......................................... 16
i. Preparation .................................................................................................... 16
ii. Integration ..................................................................................................... 16
iii. System Integration Test ........................................................................... 16
iv. User Acceptance Test ................................................................................. 17
v. Production Mode .......................................................................................... 17
VII. QueryDR Transaction ................................................... 17
VIII. Refund ....................................................................... 22
IX. Void Purchase ................................................................... 25
X. Bypass Card Selection Page on the Payment Server .......... 29
XI. Test Environment .............................................................. 31

NAPASMerchantIntegrationSpecification_2.2 page 2/32

 I. Overview
i. Document purpose
This document describe how to integrate new Internet merchant website to NAPAS
payment gateway and transaction processing flow which provided by NAPAS gateway.

Based on this, merchant can do cost analysis, what type of transaction supported.

ii. System overview

NAPAS gateway (NAPAS Payment Gateway) solution is a multi-function gateway for card
products. System is designed for requirement from customer that they want to do online
payment with International Card/ATM domestic debit cards through internet. NAPAS
Payment Gateway will help to perform almost payment process when customer doing
transaction like receive payment order, card information authorization, routing
transaction, view and report transaction.

NAPAS Payment Gateway designed and followed all international financial standards;
provide monitor function to control transaction and user in system.

iii. System glossary

Glossary Description
Payment Gateway solution provided by
NAPAS Payment Gateway
NAPAS
Web site where customer can access to
Merchant shopping cart select, order product or service before
going to do payment.
System which manage customer debit
card account and support processing
Bank system
fund transfer amount from customer card
account to merchant account
Secure Socket layer, encryption protocol
SSL
for web connection
One time password generated by bank
system and sent to customer mobile
OTP
under SMS, customer will open SMS and
get OTP code
Joint Stock Foreign Trade Bank of
VCB
Vietnam

NAPASMerchantIntegrationSpecification_2.2 page 3/32

 II. Solution Feature
i. Connection model
With purpose to support receiving order payment from merchant website, processing
transaction and return back result to initialize web site, system designed interface to
communicate through form submit and URL redirect. This help to simply connect and
integration in between with high secure feature.
Below is general connection graphic in between Service providers, bank system and
NAPAS Payment Gateway.

In this diagram, we can see that NAPAS will be the middle to communicate with all
merchant integrated, and there are some connections as list below:
- Customer-Merchant: customer access merchant website through web browser to
initial product/service selection for order.
- Merchant-NAPAS: merchant web site after integrate will send payment request to
NAPAS through URL redirect with parameters appended. This also includes redirect
transaction result back from NAPAS to merchant web site and display for customer.
- NAPAS to Bank (Issuer bank): this connection helps NAPAS to communicate with
Bank system for payment order processing.
- Bank to OTP System: when customer required to enter OTP, this connection will
help to request OTP server to generate OTP code for each customer when transact.
- OTP System to Mobile network: when OTP generated, this unique code will be
transfer to customer hand phone through mobile network. Then customer can
receive and enter to OTP authorization web page.
- Vietcombank: as settlement bank for merchant.

ii. Connection prototype

NAPASMerchantIntegrationSpecification_2.2 page 4/32

 The current connection between merchant website and NAPAS web server gateway
implement under URL redirection.
With this implementation, connection will not be depended on web page language (ASP,
PHP, JSP, .NET…) code and business model. To prepare for URL redirect connection,
NAPAS gateway will public order URL for merchant web site with list of required
parameters and checksum value (show the consistent of parameter values), merchant
website also public URL for NAPAS gateway to return back result.

iii. Function support

With the purpose designing payment gateway solution, below are standard functions will
be implement:
- Purchase function: This will perform order payment request from merchant website.
This function will be performed online through merchant and NAPAS URL redirection.
- Refund function: this will help to refund partial amount of money based on purchase
transaction. At the current, merchant staff need to access transaction management
web site provided by NAPAS to do refund customer transaction.
- Void Purchase function: allows a purchase merchant to void a purchase transaction
that has not been processed by the acquiring institution.
- Transaction query: to check status of purchase transaction successful or not.
- Authorization: system did not support authorization function at the current.
- Capture: system did not support capture function at the current.

NAPASMerchantIntegrationSpecification_2.2 page 5/32

 III. Transaction flow

i. Transaction flow

Step 1: Buying product on web

 Customer access to shopping cart of merchant on internet.

 Merchant check the validity of customer order then send payment request to NAPAS
to process transaction.

NAPASMerchantIntegrationSpecification_2.2 page 6/32

  Webpage will be redirect to NAPAS card data entry webpage to support customer
enter card information (Card no, card holder name, issue/expire date).

Step 2: Check customer information

 NAPAS will send card info to Bank host to check card and account in Bank system.

 Bank host will require customer double check payment amount, term and condition
displayed on screen when do online payment to accept payment.

Step 3, 4: Generate OTP code

 Bank host will check the valid of card account, balance, limit. If all conditions are
passed, Issuer Bank will generate and send OTP to the customer over SMS gateway
(SMS format and gateway number also displayed on web page).

Step 5: Valid customer

 Once received OTP from bank, customer will enter OTP (YYYY) to web page of bank
host to confirm transaction.

 Bank host will certify OTP. If valid, then Bank host will authorize transaction.

Step 6: Inform transaction result and settlement

 Bank host send transaction result (Accept or reject) to NAPAS. NAPAS system will
redirect result back to merchant website.

 If transaction authorized, Bank host will debit customer card account and credit
merchant account after calculate fee.

Step 7: Deliver service/product

 When received redirect result on successful transaction from NAPAS, merchant will
display result on web page and start service deliver process to customer.

NAPASMerchantIntegrationSpecification_2.2 page 7/32

 IV. Transferred Data Definition
Through URL redirect, there are certain data append to help NAPAS gateway receive and
conform payment request to bank, and vice versa, NAPAS gateway can transfer
transaction result back to merchant web site.

There are two directions which URL redirect initializes:

 Redirect from Merchant website to NAPAS gateway web site
 Redirect from NAPAS web site back to merchant website with transaction result.

i. Redirect Request from Merchant to NAPAS

To request payment transaction from merchant web site to NAPAS gateway website,
redirect process will happen along with transaction data.

At merchant web site, after select product or service and click check out button to start
payment process, merchant website will get customer transaction information and
redirect to NAPAS gateway URL address with data as below:
 https://sandbox.napas.com.vn/gateway/vpcpay.do ? + parameter string
 Parameter string format: [parameter name]=[parameter value]&[parameter
name]=[parameter value]&[parameter name]=[parameter value]&…
 The order of parameter can be exchanged, because we trace by parameter name.

Parameters definition:

Requited Example
Parameter Field type Length
Optional Value

vpc_Version The version of the Virtual Payment Client being used.

The current version is 2.0

Required Alphanumeric 1,8 2.0

vpc_Command Indicates the transaction type. This must be equal to

pay

Required Alphanumeric 1,16 pay

vpc_AccessCode The access code authenticates you on the Payment

Server so that a merchant cannot access another
merchant’s MerchantId. The access code is provided to
you when you registered your merchant profile with
your Payment Provider.

Required Alphanumeric 1,32 d03due3

vpc_MerchTxnRef A unique value created by the merchant to identify the

DO. It is used to track the progess of a transaction
and allows it to be identified on the Payment Server
should a communication’s failure occur and the DR is
not received.
It may be in part an order number or invoice number,

NAPASMerchantIntegrationSpecification_2.2 page 8/32

 but it should also reflect the transaction attempt. For
example, if a cardholder has insufficient funds on their
card and you allow them to repeat the transaction
with another credit card. The value may be test1234/1
on the first attempt, test1234/2 on the second
attempt and test1234/3 on the third attempt.
It can use text made up of any of the base US ASCII
characters in the range, hexadecimal20 to 126.

Required Alphanumeric 1,34 Test1234/1

vpc_Merchant The unique merchant Id assigned to you by your

Payment Provider.

Required Alphanumeric 1,16 TESTMERCH

ANT01

vpc_OrderInfo The merchant's identifier used to identify the order on

the Payment Server. For example, a shopping cart
number, an order number, or an invoice number.

Optional Alphanumeric 1,34 Test1234

vpc_Amount The amount of the transaction in the smallest currency

unit expressed as an integer. For example, if the
transaction amount is VND 599.54 then the
vpc_Amount is 59954.

Required Alphanumeric 1,10 59954

vpc_ReturnURL The URL that is displayed to the cardholder’s browser

when the Payment Server sends the redirect
response.It must be a complete URL. The Return URL
must start with either http:// or https:// and may be
up to 255 characters. If the return URL is not supplied,
your default vpc_ReturnURL that you nominated when
you registered your merchant profile with your
Payment Provider is used.

Required Alphanumeric 1,255 http://retur

nurl/Receipt
.asp
The Back URL must start with either http:// or https://
and may be up to 255 characters.
Required AlphaNumeric 1, 256 http://www.
vpc_BackURL
– Special domain.com
Characters /shopping.as
p
vpc_Locale Used in SSL type transactions for specifying the

NAPASMerchantIntegrationSpecification_2.2 page 9/32

 language that is used on the Payment Server pages
that are displayed to the cardholder. If the locale is
not supplied the Payment Server defined default of
‘vn’ is used.

Required Alphanumeric 2,5 vn

vpc_CurrencyCode The currency of the amount. The currency is VND

Required Alphanumeric 1,3 VND

vpc_TicketNo Ticket No is IP address of the computer of the

cardholder.

Required Alphanumeric 1,45 210.245.0.1

1

Indicates the payment gateway type. Be equal

ATM - identified transactions made on the domestic
card gateway.
vpc_PaymentGateway
INT - identified transactions made on the international
card gateway.

Optional Alphanumeric 1,10 ATM

A code issued by the Payment Server for the card type

used by the cardholder in the transaction. For a list of
card type codes, see Card Type Code (see "Card Type
vpc_CardType
Code") .

Optional Alphanumeric 1,10 Visa

A secure hash which allows the Virtual Payment Client

to authenticate the merchant and check the integrity
of the Transaction Request. Secure hash provides
vpc_SecureHash better security to merchants than Access Code.
See Checksum Calculation for detail

Required Alphanumeric 32
Note: Parameter name can be changed following merchant advice during integration.

Once NAPAS receive URL redirect process from merchant website, gateway will parsing parameter
and calculate checksum (refer to check sum value calculation) value based on those. If both check
sum values are match, then gateway web server will continue to get data from URL then form a
payment order, encrypt and send to bank system.

To get those data and redirect to NAPAS web server gateway, merchant web site should have ability
to create and get value from product selection process of customer then convert to according value
of each parameter. Those will be store into merchant transaction database for cross-check later,
customer support, and customer order processing later.

NAPASMerchantIntegrationSpecification_2.2 page 10/32

For detail of field values in certain case, just refer to below Field values description.

ii. Redirect Response from NAPAS to Merchant

To response transaction result back to merchant web site, NAPAS web server will redirect
transaction data back to predefine URL (attached in request redirect from merchant to NAPAS or
from merchant profile in NAPAS gateway database).

At NAPAS web site, after sending payment request to Bank web server, this system will ask
customer to enter OTP value before going to authorize transaction. Authorize transaction process is
limit, velocity, card, account status checking before transferring amount of money from customer
card account to merchant account with fee included. Once authorize process complete, NAPAS
gateway will receive response and redirect back to merchant URL with attached parameter string:

 http://merchant-shoping.com/response.asp? + parameter string

 Parameter string format: [parameter name]=[parameter value]&[parameter name]=[parameter
value]&[parameter name]=[parameter value]&…
 The order of parameter can be exchanged, because we trace by parameter name.

Parameters definition:

Requited Example
Parameter Field type Length
Optional Value

The version of the Virtual Payment Client being used.

The current version is 2.0
vpc_Version
Required Alphanumeric 1,8 2.0

Used in SSL type transactions for specifying the

language that is used on the Payment Server pages
that are displayed to the cardholder. If the locale is
vpc_Locale not supplied the Payment Server defined default of
‘vn’ is used.

Required Alphanumeric 2,5 vn

The value of the vpc_Comand DO input field that is

returned in the DR
vpc_Command
Required Alphanumeric 1,16 pay

The unique merchant Id assigned to you by your

Payment Provider.
vpc_Merchant
Required Alphanumeric 1,16 TESTMERCH
ANT01

vpc_MerchTxnRef A unique value created by the merchant to identify

NAPASMerchantIntegrationSpecification_2.2 page 11/32

 the DO. It is used to track the progess of a
transaction and allows it to be identified on the
Payment Server should a communication’s failure
occur and the DR is not received.
It may be in part an order number or invoice number,
but it should also reflect the transaction attempt. For
example, if a cardholder has insufficient funds on
their card and you allow them to repeat the
transaction with another credit card. The value may
be test1234/1 on the first attempt, test1234/2 on the
second attempt and test1234/3 on the third attempt.
It can use text made up of any of the base US ASCII
characters in the range, hexadecimal20 to 126.

Required Alphanumeric 1,34 Test1234/1

The amount of the transaction in the smallest

currency unit expressed as an integer. For example, if
the transaction amount is VND 599.54 then the
vpc_Amount amount is 59954.

Required Alphanumeric 1,10 59954

The currency of the order expressed as an ISO 4217
alphanumeric code. This field is case-sensitive and
must include uppercase characters only.
The merchant must be configured to accept the
vpc_CurrencyCode currency used in this field. To obtain a list of
supported currencies and codes, please contact your
Payment Provider.

Required Alphanumeric 1,3 VND

A code issued by the Payment Server for the card

type used by the cardholder in the transaction. For a
vpc_CardType
list of card type codes, see Card Type Code (see
"Card Type Code") .

Optional Alphanumeric 1,10 Visa

vpc_OrderInfo The merchant's identifier used to identify the order

on the Payment Server. For example, a shopping cart
number, an order number, or an invoice number.

Optional Alphanumeric 1,34 Test1234

A response code that is generated by the Payment

vpc_ResponseCode Server to indicate the status of the transaction.
A vpc_ResponseCode of “0” (zero) indicates that the

NAPASMerchantIntegrationSpecification_2.2 page 12/32

 transaction was processed successfully and approved
by the acquiring bank. Any other value indicates that
the transaction was declined (it went through to the
banking network) or the transaction failed (it never
made it to the banking network).
For a list of values, see Returned Response Codes
table

Required Alphanumeric 1,2 0

Payment Server transaction ID (or Shopping

Transaction Number) is a unique number generated
by the Payment Server for every transaction.
It is important to ensure that the TransactionNo is
stored for later retrieval. It is used in Merchant
vpc_TransactionNo Administration as a reference to perform refund
transactions.
This field is not returned for transactions that result
in an error condition.

Required Numeric 1,20 20090213

A value supplied by an acquirer which indicates the

batch of transactions that the specific transaction has
been grouped with for settlement. It is typically a
date in the format YYYYMMDD.
vpc_BatchNo
This field will not be returned if the transaction fails
due to an error condition.

Optional Numeric 0,8 20100809

Generated by the financial institution to indicate the

status of the transaction. The results can vary
between institutions so it is advisable to use the
vpc_ResponseCode as it is consistent across all
vpc_AcqResponseCode
acquirers. It is only included for fault finding
purposes.

Optional Alphanumeric 1,3 0

This is a message to indicate what sort of errors the

transaction encountered. This field is not provided if
vpc_Message vpc_ResponseCode has a value of zero.

Optional Alphanumeric 1,255 Success

Additional Data
vpc_AdditionalData
Optional Alphanumeric 1,255

NAPASMerchantIntegrationSpecification_2.2 page 13/32

 A secure hash which allows the Virtual Payment
Client to authenticate the merchant and check the
integrity of the Transaction Request. Secure hash
provides better security to merchants than Access
vpc_SecureHash Code.
See Checksum Calculation for detail

Required Alphanumeric 32

Note: Parameter name can be changed following merchant advice during integration.

iii. Field values description

List of value for vpc_ResponseCode field

vpc_ResponseCode meaning Value

Transaction success 0
Bank system reject (card closed, account closed) 1
Card expire 3
Limit exceeded (Wrong OTP, amount / time per day) 4
No reply from Bank 5
Bank Communication failure 6
Insufficient fund 7
Invalid checksum 8
Transaction type not support 9
Other error 10
Verify card is successful 11
Your payment is unsuccessful. Transaction exceeds amount limit. 12
You have been not registered online payment services. Please
13
contact your bank.
Invalid OTP (One time password) 14
Invalid static password 15
Incorrect Cardholder's name 16
Incorrect card number 17
Date of validity is incorrect (issue date) 18
Date of validity is incorrect (expiration date) 19
Unsuccessful transaction 20
OTP (One time password) time out 21

NAPASMerchantIntegrationSpecification_2.2 page 14/32

 Unsuccessful transaction 22
Your payment is not approved. Your card/account is ineligible for
23
payment
Your payment is unsuccessful. Transaction exceeds amount limit 24
Transaction exceeds amount limit. 25
Transactions awaiting confirmation from the bank 26
You have entered wrong authentication information 27
Your payment is unsuccessful. Transaction exceeds time limit 28
Transaction failed. Please contact your bank for information. 29
Your payment is unsuccessful. Amount is less than minimum limit. 30
Orders not found. Support for query api. 31
Orders not to make payments. Support for query api. 32
Duplicate orders. Support for query api. 33

iv. Checksum Calculation

To check the integrity of data transferring through URL redirect, there are required below
items:
 Method to calculate checksum data: can using 3DES or MD5 hashing function, most
merchant using MD5 Hashing.
 Input data for 3DES or hashing function include string which concatenate all parameter
and checksum key provided by NAPAS for each merchant profile.
 If using 3DES function, input data string will be separated every 8 characters and run
through 3DES by 32 length hexa check sum key.
 If using MD5 function to make check sum value, just concatenate input data string
plus 32 length check sum key provided by NAPAS.
 The length of check sum value is the first 32 character after running above function.
 Check sum key should be secure store by merchant website locally.

Before merchant website redirect data to NAPAS gateway server, it will calculate checksum
data and plus to URL string. NAPAS web server, once, received URL string will parsing all
data field and re calculate checksum value again, the matching process will be perform to
check the integrity of data in URL redirection. If any unmatched result, the payment request
will be rejected.

The checksum calculation and checking will be applied same process when NAPAS web
server redirects back response to merchant website.

All data field list in URL string will be calculated checksum exclusive checksum field.

NAPASMerchantIntegrationSpecification_2.2 page 15/32

 V. Data Security
i. Security channel

All redirect URL will begin with https://, this mean that data transfer in SSL channel, so
whole data string under encryption or in secure channel.

Only merchant registered and having right checksum key can pass request to NAPAS
gateway.

Checksum value will do merchant authorization and integrity of data transferred.

ii. One time Password authorization

With customer, to make more security and reduce lost and fraud, system support One
time Password verification. When purchase or do online shopping, mobile phone or other
devices (token…) to get unique code to enter and confirm transaction.

iii. Transaction rules

Each customer using bank card for online payment will be bank system monitored limit
with certain rules like;
 number of transaction per day
 total transaction amount per day
 number time of enter wrong OTP

Those rules can help to reduce risk incase card lost or stolen.

VI. Integrate and Implementation

i. Preparation
Before going to do system integration, NAPAS team will work with merchant to do
system review to make sure it compatible or qualityable for integration with NAPAS
payment gateway like:
 Merchant have shopping cart web
 Product delivery term and condition are list on web for customer clearly

ii. Integration
NAPAS will spend 01 engineer to support to merchant technical team during integration.

During integration, merchant_id and key will be provided for testing purpose only.

Estimated time for integration last around 5 day working.

iii. System Integration Test

After system integration complete, merchant will be provided testing account, card, and
using merchant tester mobile to receive OTP. At this step, Merchant still in testing mode
and transaction amount is not applicable to convert to actual cash.

NAPASMerchantIntegrationSpecification_2.2 page 16/32

 The Testing will help system run smoothly before going to user acceptance test phase.

iv. User Acceptance Test

To make sure system running well and can cover both good and exceptional case, NAPAS
will provide test script (preferred if merchant can add more case).

The UAT time for run through take around 1 week. After that merchant need to sign to
UAT minute and confirm that they accept working flow and confirm to move to
production later.

During UAT, merchant will be provided user and password to access to Merchant
Transaction Monitoring web site to check transaction.

v. Production Mode
Before moving merchant to production mode, NAPAS need to receive official letter from
merchant writing to request on production mode activate.

At this point in time, new merchant_id and checksum key will be generate and send to
merchant in two separated packages.

In production mode, merchant will be provided web interface to control their customer
transaction. Fraud report will be sent every hour if any.

During production mode, if any charge back or support request, it will be followed by
appendix in contract.

VII.QueryDR Transaction
QueryDR command allows a merchant to search for the current or the most recent
transaction receipt. It also queries for unknown transactions (a transaction request for
which a response was never received) and failed transactions.
The search is performed on the key - vpc_MerchTxnRef, so the vpc_MerchTxnRef field
must be a unique value.
If more than one Transaction Response exists with the same vpc_MerchTxnRef, the most
recent Transaction Response is returned.

Request Input Fields are:

Requited Example
Parameter Field type Length
Optional Value
vpc_Version The version of the API being used. The current
version is 2.2
Required Alphanumeric 1,8 2.2

vpc_Command Indicates the transaction type. This must be equal to

queryDR
Required Alphanumeric 1,16 queryDR

NAPASMerchantIntegrationSpecification_2.2 page 17/32

 vpc_AccessCode The access code authenticates you on the Payment
Server so that a merchant cannot access another
merchant’s MerchantId. The access code is provided
to you when you registered your merchant profile
with your Payment Provider.
Required Alphanumeric 8 d03due3
vpc_Merchant The unique merchant Id assigned to you by your
Payment Provider.
Required Alphanumeric 1,16 TESTMERCH
ANT01
vpc_MerchTxnRef It is the primary key used to search the progress of a
transaction in the event of a communication's failure
where no DR is received.
Required Alphanumeric 1,34 est1234/1
-
Special
characters
vpc_User This field is a special user created to use this
function.
Required Alphanumeric 1,20 usertest
vpc_Password The password used to authorize the AMA user access
to this function.
Required Alphanumeric 1,16 passtest
vpc_SecureHash Used to check the integrity of the request.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

Transaction Response Fields are:

Note: vpc_TxnResponseCode and VPC_Message will always appear in the DR.

Other fields may not be returned if the transaction was unsuccessful.
The fields returned in the DR are the same as the original transaction, but includes two
additional DR fields. The fields that are included in a DR when using QueryDR are:

Requited Example
Parameter Field type Length
Optional Value
The version of the Virtual Payment Client being used.
vpc_Version
Required Alphanumeric 1,8 2.0

Used in SSL type transactions for specifying the

language that is used on the Payment Server pages
vpc_Locale that are displayed to the cardholder. If the locale is
not supplied the Payment Server defined default of
‘vn’ is used.

NAPASMerchantIntegrationSpecification_2.2 page 18/32

 Optional Alphanumeric 2,5 vn

The value of the vpc_Comand DO input field that is

returned in the DR
vpc_Command
Required Alphanumeric 1,16 queryDR

The unique merchant Id assigned to you by your

Payment Provider.
vpc_Merchant
Required Alphanumeric 1,16 TESTMERCH
ANT01

A unique value created by the merchant to identify

the DO. It is used to track the progess of a
transaction and allows it to be identified on the
Payment Server should a communication’s failure
occur and the DR is not received.
It may be in part an order number or invoice number,
but it should also reflect the transaction attempt. For
example, if a cardholder has insufficient funds on
vpc_MerchTxnRef
their card and you allow them to repeat the
transaction with another credit card. The value may
be test1234/1 on the first attempt, test1234/2 on the
second attempt and test1234/3 on the third attempt.
It can use text made up of any of the base US ASCII
characters in the range, hexadecimal20 to 126.

Required Alphanumeric 1,34 Test1234/1

The amount of the transaction in the smallest

currency unit expressed as an integer. For example, if
the transaction amount is VND 599.54 then the
vpc_Amount
amount is 59954.

Optional Alphanumeric 1,10 59954

The currency of the order expressed as an ISO 4217
alphanumeric code. This field is case-sensitive and
must include uppercase characters only.
The merchant must be configured to accept the
vpc_CurrencyCode currency used in this field. To obtain a list of
supported currencies and codes, please contact your
Payment Provider.

Optional Alphanumeric 1,3 VND

A code issued by the Payment Server for the card

vpc_CardType type used by the cardholder in the transaction. For a
list of card type codes, see Card Type Code (see

NAPASMerchantIntegrationSpecification_2.2 page 19/32

 "Card Type Code") .

Optional Alphanumeric 1,10 Visa

vpc_OrderInfo The merchant's identifier used to identify the order

on the Payment Server. For example, a shopping cart
number, an order number, or an invoice number.

Optional Alphanumeric 1,34 Test1234

A response code that is generated by the Payment

Server to indicate the status of the transaction.
A vpc_TxnResponseCode of “0” (zero) indicates that
the transaction was processed successfully and
approved by the acquiring bank. Any other value
indicates that the transaction was declined (it went
vpc_TxnResponseCode
through to the banking network) or the transaction
failed (it never made it to the banking network).
For a list of values, see Returned Response Codes
table

Required Alphanumeric 1,2 0

Payment Server transaction ID (or Shopping

Transaction Number) is a unique number generated
by the Payment Server for every transaction.
It is important to ensure that the TransactionNo is
stored for later retrieval. It is used in Merchant
vpc_TransactionNo Administration as a reference to perform refund
transactions.
This field is not returned for transactions that result
in an error condition.

Optional Numeric 1,20 20090213

A value supplied by an acquirer which indicates the

batch of transactions that the specific transaction has
been grouped with for settlement. It is typically a
date in the format YYYYMMDD.
vpc_BatchNo
This field will not be returned if the transaction fails
due to an error condition.

Optional Numeric 0,8 20100809

Generated by the financial institution to indicate the

status of the transaction. The results can vary
vpc_AcqResponseCode between institutions so it is advisable to use the
vpc_ResponseCode as it is consistent across all
acquirers. It is only included for fault finding

NAPASMerchantIntegrationSpecification_2.2 page 20/32

 purposes.

Optional Alphanumeric 1,3 0

This is a message to indicate what sort of errors the

transaction encountered. This field is not provided if
vpc_Message vpc_ResponseCode has a value of zero.

Optional Alphanumeric 1,255 Success

Additional Data
vpc_AdditionalData
Optional Alphanumeric 1,255

The number of the card to be used for processing the

payment. It can only be a long integer value with no
white space or formatting characters.
vpc_CardNumber
Optional Numeric 15,32 9704360000
000000028

The name of the holder card to be used for

processing the payment.
vpc_CardHolderName
Optional Alphanumeric 4,64 Nguyen Van
Nam

The expiry date of the card to be processed for

payment. The format for this is MMYY, for example,
for an expiry date of May 2009, the value would be
0509. The value must be expressed as a 4-digit
vpc_ExpiredDate
number (integer) with no white space or formatting
characters.

Optional Numeric 4 0216

It is a unique transaction identifier that is generated

by the merchant to identify the 3DS transaction. It is
a 20-byte field that is Base64 encoded to produce a
28-character value.
vpc_3DSXID
Optional Alphanumeric 28 uyPfGIgsoF
QhklkIsto+I
FWs92s=

The 3-D Secure Electronic Commerce Indicator, which

is set to '05' when the cardholder authenticates OK,
and '08' when the cardholder is not enrolled. (These
vpc_3DSECI values may change depending on the locale or
issuer).

Optional Numeric 2 08

NAPASMerchantIntegrationSpecification_2.2 page 21/32

 Either '3DS' or 'SPA'.
vpc_VerType
Optional Alphanumeric 3,20 3DS

The status codes used by the Payment Server

vpc_VerStatus
Optional Alphanumeric 1 N
vpc_SecureHash Used to check the integrity of the response.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

VIII. Refund
Refund allows you to refund funds for a previous purchase or capture transaction from the
merchant's account back to the cardholder's account.

Refunds can only be performed for a previously completed a purchase or capture transaction
for the particular order. The merchant can run any number of refund transactions on the
original transaction, but cannot refund more than has been obtained via a purchase or
capture transaction.

There are two ways to refund the funds:

1. Manually using Merchant Administration. This is the simplest method if the merchant
does not have many refund transactions.
2. Using the Refund command via the directly perform refunds from the merchant's
application.

Request Fields
Requited Example
Parameter Field type Length
Optional Value
vpc_Version The version of the API being used. The current
version is 2.1
Required Alphanumeric 1,8 2.1

vpc_Command Indicates the transaction type. This must be equal to

refund
Required Alphanumeric 1,16 refund
vpc_AccessCode The access code authenticates you on the Payment
Server so that a merchant cannot access another
merchant’s MerchantId. The access code is provided
to you when you registered your merchant profile
with your Payment Provider.
Required Alphanumeric 8 d03due3
vpc_Merchant The unique merchant Id assigned to you by your
Payment Provider.
Required Alphanumeric 1,16 SMLTEST

NAPASMerchantIntegrationSpecification_2.2 page 22/32

 vpc_MerchTxnRef It is the primary key used to search the progress of a
transaction in the event of a communication's failure
where no DR is received.
Required Alphanumeric 1,34 est1234/1
-
Special
characters
vpc_User This field is a special user created to use this
function.
Required Alphanumeric 1,20 usertest
vpc_Password The password used to authorize the AMA user access
to this function.
Required Alphanumeric 1,16 passtest
vpc_TransactionNo A unique number generated by the Payment Server.
It is the reference value of the transaction in the
Payment Server. This is the value that must be used
for a Refund.
Required Numeric 1,19 123456789
vpc_Amount The amount of the refund transaction in the smallest
currency unit expressed as an integer. For example, if
the transaction amount is $49.95 then the amount in
cents is 4995.
Required Alphanumeric 1,15
vpc_CurrencyCode The currency of the order expressed as an ISO 4217
alphanumeric code. This field is case-sensitive and
must include uppercase characters only.
The merchant must be configured to accept the
currency used in this field. To obtain a list of
supported currencies and codes, please contact your
Payment Provider.
Optional Alpha 3 VND
vpc_SecureHash Used to check the integrity of the request.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

Transaction Response Fields are:

Note : vpc_TxnResponseCode and VPC_Message will always appear in the DR. Other fields
may not be returned if the transaction was unsuccessful.
Requited Example
Parameter Field type Length
Optional Value
vpc_Version The version of the API being used. The current
version is 2.1
Required Alphanumeric 1,8 2.1

vpc_Command Indicates the transaction type. This must be equal to

NAPASMerchantIntegrationSpecification_2.2 page 23/32

 refund
Required Alphanumeric 1,16 refund
vpc_Merchant The unique merchant Id assigned to you by your
Payment Provider.
Required Alphanumeric 1,16 SMLTEST
vpc_MerchTxnRef It is the primary key used to search the progress of a
transaction in the event of a communication's failure
where no DR is received.
Required Alphanumeric 1,34 est1234/1
-
Special
characters
vpc_OrgTransactionNo The transaction reference number of the original
purchase transaction.
Required Numeric 1,19 123456789
vpc_RefundTransactionNo A unique number generated by the Payment Server.
It is the reference value of the transaction in the
Payment Server. This is the value that must be used
for a Refund.
Required Numeric 1,19 123456789
vpc_Amount The amount of the refund transaction in the smallest
currency unit expressed as an integer. For example, if
the transaction amount is $49.95 then the amount in
cents is 4995.
Required Alphanumeric 1,15
vpc_CurrencyCode The currency of the order expressed as an ISO 4217
alphanumeric code. This field is case-sensitive and
must include uppercase characters only.
The merchant must be configured to accept the
currency used in this field. To obtain a list of
supported currencies and codes, please contact your
Payment Provider.
Optional Alpha 3 VND
vpc_TxnResponseCode A response code that is generated by the Payment
Server to indicate the status of the transaction. A
vpc_TxnResponseCode of “0” (zero) indicates that
the transaction was processed successfully and
approved by the acquiring bank. Any other value
indicates the transaction was declined.
See Response Code.
Required Alphanumeric 1,2 0
vpc_AcqResponseCode Acquirer's Response Code is generated by the
financial institution to indicate the status of the
transaction. The results can vary between institutions
so it is advisable to use the vpc_TxnResponseCode as
it is consistent across all acquirers. It is only included
for fault finding purposes.
Optional Alphanumeric 2,3 00
vpc_ReceiptNo This is also known as the Reference Retrieval Number
(RRN), which is a unique identifier. This value is

NAPASMerchantIntegrationSpecification_2.2 page 24/32

 passed back to the cardholder for their records if the
merchant application does not generate its own
receipt number.
Optional Alphanumeric 1,18 RP12345
vpc_BatchNo A date supplied by an acquirer to indicate when this
transaction will be settled. If the batch has today's
date then it will be settled the next day. When the
acquirer closes the batch at the end of the day, the
date will roll over to the next processing day's date.
Optional Alphanumeric 1,8 20131021
vpc_AuthorizeId Authorization Identification Code issued by the
Issuer/Acquirer to approve or deny a transaction.
This field is 6-digits maximum and is not returned for
transactions that are declined or fail due to an error
condition.
Optional Numeric 0,6 123456
vpc_CardType A code issued by the Payment Server for the card
type used by the cardholder in the transaction. For a
list of card type codes, see Card Type Code table
Optional Alphanumeric 2,10 Mastercard
vpc_AuthorisedAmount The total amount of the original transaction.
Optional Numeric 1,15
vpc_RefundedAmount The amount of the refund transaction request
Optional Numeric 1,15
vpc_TicketNo Allows you to include a ticket number, such as an
airline ticket number in the transaction request. The
ticket number is stored on the Payment Server
Optional Alphanumeric 1,32 ABC123
vpc_SecureHash Used to check the integrity of the request.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

IX. Void Purchase

Void Purchase allows a purchase merchant to void a purchase transaction that has not been
processed by the acquiring institution. It is not available for Auth/Capture mode merchants.
This transaction is not possible for Debit and EBT transactions.

The merchant can only run one 'Void Purchase' transaction on the original 'Purchase'
transaction as it completely removes the purchase transaction as though it never occurred.

The Admin Void Purchase must be run before the acquiring institution processes the batch
containing the original purchase transaction.

Your Payment Provider must enable this function on your Merchant Profile for you to use
either of these methods

NAPASMerchantIntegrationSpecification_2.2 page 25/32

 + Using the voidPurchase command via the directly perform refunds from the merchant's
application.

Request Fields

Requited Example
Parameter Field type Length
Optional Value
vpc_Version The version of the API being used. The current
version is 2.1
Required Alphanumeric 1,8 2.1

vpc_Command Indicates the transaction type. This must be equal to

voidPurchase
Required Alphanumeric 1,16 refund
vpc_AccessCode The access code authenticates you on the Payment
Server so that a merchant cannot access another
merchant’s MerchantId. The access code is provided
to you when you registered your merchant profile
with your Payment Provider.
Required Alphanumeric 8 d03due3
vpc_Merchant The unique merchant Id assigned to you by your
Payment Provider.
Required Alphanumeric 1,16 SMLTEST
vpc_MerchTxnRef It is the primary key used to search the progress of a
transaction in the event of a communication's failure
where no DR is received.
Required Alphanumeric 1,34 est1234/1
-
Special
characters
vpc_User This field is a special user created to use this
function.
Required Alphanumeric 1,20 usertest
vpc_Password The password used to authorize the AMA user access
to this function.
Required Alphanumeric 1,16 passtest
vpc_TransactionNo The transaction reference number of the original
Purchase transaction.
Required Numeric 1,19 123456789
vpc_SecureHash Used to check the integrity of the request.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

Transaction Response Fields are:

NAPASMerchantIntegrationSpecification_2.2 page 26/32

 Note : vpc_TxnResponseCode and VPC_Message will always appear in the DR. Other fields
may not be returned if the transaction was unsuccessful.

The fields included in a DR from the Virtual Payment Client when using voids are:
Requited Example
Parameter Field type Length
Optional Value
vpc_Version The version of the API being used. The current
version is 2.1
Required Alphanumeric 1,8 2.1

vpc_Command Indicates the transaction type. This must be equal to

voidPurchase
Required Alphanumeric 1,16 voidPurchas
e
vpc_Merchant The value of the vpc_Merchant input field returned in
the DR.
Required Alphanumeric 1,16 SMLTEST
vpc_MerchTxnRef The value of the vpc_MerchTxnRef field returned in
the DR.
Required Alphanumeric 1,34 est1234/1
-
Special
characters
vpc_OrgTransactionNo The transaction reference number of the original
purchase transaction.
Required Numeric 1,19 123456789
vpc_VoidTransactionNo A unique number generated by the Payment Server.
It is the reference value of the transaction in the
Payment Server. This is the value that must be used
for a Void Purchase.
Required Numeric 1,19 123456789
vpc_Message A message to indicate any errors the transaction may
have encountered.
Optional Alphanumeric 10,200
vpc_TxnResponseCode A response code that is generated by the Payment
Server to indicate the status of the transaction. A
vpc_ResponseCode of “0” (zero) indicates that the
transaction was processed successfully and approved
by the acquiring bank. Any other value indicates the
transaction was declined.
See Response Code.
Required Alphanumeric 1,2 0
vpc_AcqResponseCode Acquirer's Response Code is generated by the
financial institution to indicate the status of the
transaction. The results can vary between institutions
so it is advisable to use the vpc_TxnResponseCode as
it is consistent across all acquirers. It is only included
for fault finding purposes.
Optional Alphanumeric 2,3 00

NAPASMerchantIntegrationSpecification_2.2 page 27/32

 vpc_ReceiptNo This is also known as the Reference Retrieval Number
(RRN), which is a unique identifier. This value is
passed back to the cardholder for their records if the
merchant application does not generate its own
receipt number.
Optional Alphanumeric 1,18 RP12345
vpc_BatchNo A date supplied by an acquirer to indicate when this
transaction will be settled. If the batch has today's
date then it will be settled the next day. When the
acquirer closes the batch at the end of the day, the
date will roll over to the next processing day's date.
Optional Alphanumeric 1,8 20131021
vpc_AuthorizeId A code issued by the acquiring bank to approve or
deny the transaction. This may not always be upplied
by all acquirers.
Optional Numeric 1,12 ABC12345
vpc_CardType A code issued by the Payment Server for the card
type used by the cardholder in the transaction. For a
list of card type codes, see Card Type Code table
Optional Alphanumeric 2,10 Mastercard
vpc_AuthorisedAmount The net amount of the original purchase transaction.
If successful, this should be 0.
Optional Numeric 1,12 4996
vpc_RefundedAmount The net refunded amount in the smallest currency
unit expressed as an integer
Optional Numeric 1,15 4996
vpc_TicketNo Use to include a ticket number, such as an airline
ticket number in the DO. The ticket number is stored
on the Payment Server database for that transaction.
The ticket number is stored on the Payment Server
database for that transaction and returned in the DR
for refunds.
Optional Alphanumeric 1,32 ABC123
vpc_ CapturedAmount The net captured amount. In a successful void
purchase, this should be 0
Optional Alpha 3 VND
vpc_SecureHash Used to check the integrity of the request.
Required Alphanumeric 32 68798ab025
9eb01be7bb
e2a80
7171f83

NAPASMerchantIntegrationSpecification_2.2 page 28/32

 X. Bypass Card Selection Page on the Payment
Server
This is used in 3-Party Payments to bypass the Payment Server payments page that displays
the logos of all the cards the payment processor will accept.

DO Fields - Bypass Card Selection Page

The fields that are included in a DO when using Bypass Card Selection are:

Requited
Parameter Field type Length Example Value
Optional
Indicates the payment gateway type. Be equal
ATM - identified transactions made on the domestic card
gateway.
vpc_PaymentGateway
INT - identified transactions made on the international card
gateway.

Optional Alphanumeric 1,10 ATM

A code issued by the Payment Server for the card type used
by the cardholder in the transaction. For a list of card type
vpc_CardType codes, see Card Type Code (see "Card Type Code") .

Optional Alphanumeric 1,10 Visa

Card Type Code

Code - International card Name

Visa Visa Card
Mastercard Master Card
Amex American Express
JCB JCB

Code - Domestic card Name

VCB Vietcombank
TCB Techcombank
VIB VIB Bank
ABB ABBank
STB Sacombank
MSB Maritime Bank

NAPASMerchantIntegrationSpecification_2.2 page 29/32

 NVB Navibank
CTG Vietinbank
DAB DongABank
HDB HDBank
VAB VietABank
VPB VPBank
ACB ACB
MB MBBank
GPB GPBank
EIB Eximbank
OJB OceanBank
NASB BacABank
OCB OricomBank
TPB TPBank
LPB LienVietPostBank
SEAB Seabank
BIDV BIDV
VARB AgriBank
BVB BaoVietBank
SHB SHB
KLB KienLongBank
SCB SCB

NAPASMerchantIntegrationSpecification_2.2 page 30/32

 XI. Test Environment
NAPAS Payment Gateway

Virtual Payment Client URL: https://sandbox.napas.com.vn/gateway/vpcpay.do

Merchant ID: SMLTEST
Access Code: ECAFAB
Secure Hash: 198BE3F2E8C75A53F38C1C4A5B6DBA27

QueryDR

Virtual Payment Client URL: https://sandbox.napas.com.vn/gateway/vpcdps

Merchant ID: SMLTEST
Access Code: ECAFAB
Username: usertest
Password: passtest
Secure Hash: 198BE3F2E8C75A53F38C1C4A5B6DBA27

Refund

Virtual Payment Client URL: https://sandbox.napas.com.vn/gateway/vpcdps

Merchant ID: SMLTEST
Access Code: ECAFAB
Username: usertest
Password: passtest
Secure Hash: 198BE3F2E8C75A53F38C1C4A5B6DBA27

Domestic cards test

1. Card successful
Card Name: NGUYEN VAN A
Card Number: 9704000000000018
Card Expdate: 03/07

2. Card Lock
Card Name: NGUYEN VAN A
Card Number: 9704000000000026
Card Expdate: 03/07

3. Not sufficient funds

Card Name: NGUYEN VAN A
Card Number: 9704000000000034
Card Expdate: 03/07

4. Card limit
Card Name: NGUYEN VAN A
Card Number: 9704000000000042
Card Expdate: 03/07

NAPASMerchantIntegrationSpecification_2.2 page 31/32

 Static OTP for test: OTP

Visa/MasterCard test:

1. MasterCard
Card Number: 5123456789012346
Card Expdate: 05/17
Cvv: 123

2. Visa
Card Number 4005550000000001
Card Expdate: 05/17
Cvv: 123

NAPASMerchantIntegrationSpecification_2.2 page 32/32