Napas Payment Gateway Techspec v3.0

NATIONAL PAYMENT CORPORATION OF VIETNAM
PAYMENT GATEWAY
TECHNICAL SPECIFICATION
Version 3.0
Hanoi, Oct 2017

Table of contents
Table of contents .................................................................................................................................... 1
1 Introduction .................................................................................................................................... 3
1.1 Audience ................................................................................................................................. 3
1.2 Scope ....................................................................................................................................... 3
1.3 Support.................................................................................................................................... 3
1.4 How to Use this Document ..................................................................................................... 3
2 Technical Specification .................................................................................................................... 5
2.1 Security Access Control ........................................................................................................... 5
2.1.1 The OAuth 2.0 Authorization .......................................................................................... 5
2.1.2 SSL Protocol..................................................................................................................... 5
2.2 Test Information ..................................................................................................................... 6
2.2.1 Authentication Information ............................................................................................ 6
2.2.2 Card Information ............................................................................................................. 6
3 Hosted Checkout Implementation .................................................................................................. 7
3.1 Data Key transaction ............................................................................................................... 7
3.2 Pay / Pay with returned Token / Create Token – integrate with Napas Hosted Form ........... 8
3.3 Pay / Pay with returned Token / Create Token – integrate with Napas Payment Page ....... 11
3.4 Receive response from Napas............................................................................................... 14
4 Direct API Implementation ........................................................................................................... 16
4.1 Pay / Authorize / Capture / Void / Refund............................................................................ 16
Refund Domestic transaction ........................................................................................................... 16
4.2 Pay with 3DSecure transaction ............................................................................................. 25
4.3 Purchase OTP transaction – integrate with Napas Hosted Checkout ................................... 35
4.4 Retrieve Order transaction ................................................................................................... 43
4.5 Delete Token transaction ...................................................................................................... 52
4.6 Error parameters................................................................................................................... 53
5 Response Code .............................................................................................................................. 54
5.1 International Card Process .................................................................................................... 54
5.2 Domestic Card Process.......................................................................................................... 56
6 Appendix A: Napas Hosted Form Screenshots.............................................................................. 58
6.1 Create Token transaction ...................................................................................................... 58
6.2 Pay / Pay with returned Token transaction .......................................................................... 59
7 Appendix B: Transaction flow ....................................................................................................... 60
7.1 Pay with 3DSecure transaction flow ..................................................................................... 60
1
Document Control
Date Author Reviewer Note
17-Oct- Do Viet Thanh Nguyen Thi Tuyet Initial version
2017
2
1 Introduction
1.1 Audience
This document is intended to be used by developers, technical personnel and business analysts
to facilitate a successful integration by a merchant to the Payment Gateway.
This is reflected in the layout of the document, which covers the submission of data to the
Payment Gateway.
1.2 Scope
This document describes the interfaces, messages, data formats, and responses used for
integration to the Payment Gateway. The focus of this document is the integration of the token
payments method.
This is a technical API document and as such is concerned with specific message formats.
The services covered in this document are Token transactions.
1.3 Support
For any assistance or information pertaining to existing or new Payment Gateway services,
contact Payment Gateway Support.
1.4 How to Use this Document

All technical APIs described in this document are displayed in the form of table by
main transactions:
Hosted Checkout Implementation
- Data Key transaction
- Pay / Pay with returned Token / Create Token – integrate with Hosted Form
- Pay / Pay with returned Token / Create Token – integrate with Payment Page
Direct API Implementation
- Pay / Authorize / Capture / Void / Refund transaction
- Refund Domestic transaction
- Pay with 3DSecure transaction
- Purchase OTP transaction
- Retrieve Order International transaction
- Retrieve Order Domestic transaction
- Delete Token transaction
3
All API’s fields are described by their attributes:
- Field Name: name of field as used in JSON form

- Field Type: data type of the field
- Description
Field Usage:
- R: Required – field must be presented

- C: Conditional – presenting this field if some conditions are met.
- O: Optional – field is optional
4
2 Technical Specification
2.1 Security Access Control
2.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.
Protocol Flow:
A – Merchant sends request to get an access_token to Authorization Server.

B – Authorization Server authorizes Merchant and returns an access_token.
C – Merchant captures the returned access_token and uses it to access to APIs in Resource
Server.
D – Resource server serves functional APIs to Merchant.
2.1.2 SSL Protocol
The communication between Merchant and Napas system uses HTTPS connection with
TLS1.2 protocol, so that data will be securely encrypted during transmission.
5
2.2 Test Information
2.2.1 Authentication Information
Authentication endpoint: https://dps-staging.napas.com.vn/api/oauth/token
Authentication elements:
- grant_type: password
- client_id: APITEST
- client_secret: TT3F6AM5UQZXJEJXAWJ8CHVC9ZJ02A51
- username: apitest
- password: fPJFVp5qnCWeFmtd
2.2.2 Card Information

Cardholder Name Effective Date CVV / Static
Card Schemes Card Number
OTP
MasterCard (3ds) 5123450000000008 05/17 100
MasterCard
5111111111111118 05/17 100
(non 3ds)
Visa 4005550000000019 05/17 100
American Express 345678901234564 05/17 100
JCB 3528000000000007 05/17 100
9704000000000018 otp
9704020000000018
9704000000000026
Domestic Card Nguyen Van A 03/07
9704000000000034
9704000000000042
9704020000000018
6
3 Hosted Checkout Implementation
3.1 Data Key transaction
Merchant uses this transaction to obtain the secure keys needed for integrating Napas Hosted
Checkout.
URL https://dps-
staging.napas.com.vn/api/rest/version/1/merchant/{merchantId}/datakey
HTTP Method POST
Content-Type Application/json
Authentication This operation requires authentication via the following method:

 OAuth2 (see section 2.1 “Security Access Control”).
Fields detail
Field name Field type Request Response Description
Message Message
apiOperation string R R DATA_KEY: Request to obtain secure keys for integrating Napas Hosted Form.
inputParameters Input parameters data group.
inputParameters.clientI string R IP of the customer client

P
inputParameters.deviceI string R Customer identifier, this will be returned to merchant after processing
d transaction.
inputParameters.enviro string R WebApp: use to integrate on Web Applications
nment MobileApp: use to integrate on Mobile Applications
inputParameters.cardSc string R CreditCard: use in case of international cards.
heme AtmCard: use in case of domestic cards
inputParameters.enable string R Supports 3DSecure for authorizing cardholder when using CreditCard.
3DSecure
true: enable 3DSecure flow
false: disable 3DSecure flow
result string R A system-generated high level overall result of the operation

Value must be a member of the following list. The values are case sensitive.
SUCCESS: The operation was successfully processed
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
ERROR: The operation was rejected during validation
dataKey string C A system-generated string that represents the session of merchant which wants
to do server-hosted form.
napasKey string C A system-generated string used for security reasons. This is a public key, used in
checking signature of Napas.
7
3.2 Pay / Pay with returned Token / Create Token – integrate with Napas
Hosted Form
- Pay: Customer pays for goods / services only.
- Pay with returned Token: Customer pays for goods / services, and also receives a
Token that can be used for payment afterwards.
- Create Token: Customer inputs card information, then receives a Token that can be
used for payment afterwards.
To integrate Napas Hosted Form, merchant must obtain dataKey and napasKey (refer to 3.1.
DataKey transaction), then generate a HTML script as below:
<form id="merchant-form" action="https://web.merchant.com/result-page"
method="POST"></form>
<div id="napas-widget-container"></div>
<script
type="text/javascript"
id="napas-widget-script"
src="https://dps-
staging.napas.com.vn/api/restjs/resources/js/napas.hostedform.min.js"
merchantId="APITEST"
clientIP="192.168.1.1"
deviceId="ID_12345678"
environment="WebApp"
cardScheme="CreditCard"
enable3DSecure="true"
apiOperation="PAY"
orderAmount="150000"
orderCurrency="VND"
orderReference="Thanh toan hoa don"
orderId="ORD_841015"
channel="7399"
sourceOfFundsType="CARD"
dataKey="232BBF38F081EB94C086E1BDC20E155C9C381FF2104E0A91ADA2B16B86206449D56CE780D2
AD5ED8E29C83B4AF515C656CCDD34C377D4A90"
napasKey="MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCX0yRwcCBZIMrOhtdr2eO2hLlLtSmGERW+N
M1LoXLbg11fWPucJkqwqtLFrVHwPs6RR5wqsOk7UNf8PDLEgZFB3ybUed/XeWKpSBuDO+pZf5neVCZ0blzD
fZlaNaY3IL34QIgu9/zq/BlyjbIu/BSKl//Ugatc+bVRJX0+uD1XJwIDAQAB:MIIBsDCCARkCBgFaR+TbpT
ANBgkqhkiG9w0BAQUFADAeMRwwGgYDVQQDExNUZXN0IENBIENlcnRpZmljYXRlMB4XDTE3MDIxNjE3MDc0N
VoXDTE3MDIxNzE3MDc0NVowHjEcMBoGA1UEAxMTVGVzdCBDQSBDZXJ0aWZpY2F0ZTCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEAl9MkcHAgWSDKzobXa9njtoS5S7UphhEVvjTNS6Fy24NdX1j7nCZKsKrSxa1R8D7
OkUecKrDpO1DX/DwyxIGRQd8m1Hnf13liqUgbgzvqWX+Z3lQmdG5cw32ZWjWmNyC9+ECILvf86vwZco2yLv
wUipf/1IGrXPm1USV9Prg9VycCAwEAATANBgkqhkiG9w0BAQUFAAOBgQBIUEse2etILP+33D9YZbgU0efBR
cSa94pgyC2ErymvHwWXMs9urF2hyK3Xy7+Ul8mg4m0iDVwBIBv0X1T0cQACe07ZOpu4M2B4XpdGri4Y8KDu
oHMSb23w4IhvneFUOWf0+kXbJoczKalT/y8Y866zn9OOTLPdUbsxZ5Kto5WLXw=="
8
>
</script>
Parameters details
Field name Field Description Pay Pay with Create
Type returned Token
Token
action string URL of the webpage that shows transaction result, includes https://... R R R
merchantId string Merchant identifier R R R
clientIP string Customer’s ip address RE RE RE
deviceId string Customer’s identifier, this will be returned after processing transaction RE RE RE
environment string Integration environment: RE RE RE
WebApp: desktop web
MobileApp: mobile web/mobile app
cardScheme string Card schemes in use: RE RE RE
CreditCard: international cards (Visa, Mastercard, Amex…)
AtmCard: domestic cards
enable3DSecure string Supports 3DSecure to authorize cardholder (always be false with RE RE RE

AtmCard)
true: enables 3DSecure flow
false: disables 3DSecure flow
apiOperation string PAY: normal payment with card details. R R
PAY_WITH_RETURNED_TOKEN: pay and tokenize card details.
orderAmount string Order amount (display on form) R R
orderCurrency string Order currency (display on form) R R
orderReference string Order short description (display on form) R R
orderId String Order identifier (must be unique) R R R

(max 40)
channel string Merchant business code R R
sourceOfFundsType string Always be CARD R R
dataKey string Secured key for communication with Napas R R R
9
napasKey string Secured key for data encryption R R R
serviceCode string Reserved for future use O O
language string Napas Hosted Form display language O O O
vi: Vietnamese
en: English
bannerUrl string Custom banner for promotions… This must be a full URL includes O O O
https://... and must be on the same domain with merchant’s website that
integrates Napas Hosted Form
*R: field must be presented
*RE: field must be presented and have the same value as in Data Key transaction request.
*O: field is optional
10
3.3 Pay / Pay with returned Token / Create Token – integrate with Napas
Payment Page
- Pay: Customer pays for goods / services only.
- Pay with returned Token: Customer pays for goods / services, and also receives a
Token that can be used for payment afterwards.
- Create Token: Customer inputs card information, then receives a Token that can be
used for payment afterwards.
To integrate Napas Payment Page, merchant must obtain dataKey and napasKey (refer to 3.1.
DataKey transaction), then generate a HTML script as below:
<form id="merchant-form" action="https://web.merchant.com/result-page"
method="POST"></form>
<div id="napas-widget-container"></div>
<script
type="text/javascript"
id="napas-widget-script"
src="https://dps-
staging.napas.com.vn/api/restjs/resources/js/napas.paymentpage.min.js"
merchantId="APITEST"
clientIP="192.168.1.1"
deviceId="ID_12345678"
environment="WebApp"
cardScheme="CreditCard"
enable3DSecure="true"
apiOperation="PAY"
orderAmount="150000"
orderCurrency="VND"
orderReference="Thanh toan hoa don"
orderId="ORD_841015"
channel="7399"
sourceOfFundsType="CARD"
dataKey="232BBF38F081EB94C086E1BDC20E155C9C381FF2104E0A91ADA2B16B86206449D56CE780D2
AD5ED8E29C83B4AF515C656CCDD34C377D4A90"
napasKey="MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCX0yRwcCBZIMrOhtdr2eO2hLlLtSmGERW+N
M1LoXLbg11fWPucJkqwqtLFrVHwPs6RR5wqsOk7UNf8PDLEgZFB3ybUed/XeWKpSBuDO+pZf5neVCZ0blzD
fZlaNaY3IL34QIgu9/zq/BlyjbIu/BSKl//Ugatc+bVRJX0+uD1XJwIDAQAB:MIIBsDCCARkCBgFaR+TbpT
ANBgkqhkiG9w0BAQUFADAeMRwwGgYDVQQDExNUZXN0IENBIENlcnRpZmljYXRlMB4XDTE3MDIxNjE3MDc0N
VoXDTE3MDIxNzE3MDc0NVowHjEcMBoGA1UEAxMTVGVzdCBDQSBDZXJ0aWZpY2F0ZTCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEAl9MkcHAgWSDKzobXa9njtoS5S7UphhEVvjTNS6Fy24NdX1j7nCZKsKrSxa1R8D7
OkUecKrDpO1DX/DwyxIGRQd8m1Hnf13liqUgbgzvqWX+Z3lQmdG5cw32ZWjWmNyC9+ECILvf86vwZco2yLv
wUipf/1IGrXPm1USV9Prg9VycCAwEAATANBgkqhkiG9w0BAQUFAAOBgQBIUEse2etILP+33D9YZbgU0efBR
cSa94pgyC2ErymvHwWXMs9urF2hyK3Xy7+Ul8mg4m0iDVwBIBv0X1T0cQACe07ZOpu4M2B4XpdGri4Y8KDu
oHMSb23w4IhvneFUOWf0+kXbJoczKalT/y8Y866zn9OOTLPdUbsxZ5Kto5WLXw=="
11
>
</script>
Parameters details
Field name Field Description Pay Pay with Create
Type returned Token
Token
action string URL of the webpage that shows transaction result, includes https://... R R R
merchantId string Merchant identifier R R R
clientIP string Customer’s ip address RE RE RE
deviceId string Customer’s identifier, this will be returned after processing transaction RE RE RE
environment string Integration environment: RE RE RE
WebApp: desktop web
MobileApp: mobile web/mobile app
cardScheme string Card schemes in use: RE RE RE
CreditCard: international cards (Visa, Mastercard, Amex…)
AtmCard: domestic cards
enable3DSecure string Supports 3DSecure to authorize cardholder (always be false with RE RE RE

AtmCard)
true: enables 3DSecure flow
false: disables 3DSecure flow
apiOperation string PAY: normal payment with card details. R R
PAY_WITH_RETURNED_TOKEN: pay and tokenize card details.
orderAmount string Order amount (display on form) R R
orderCurrency string Order currency (display on form) R R
orderReference string Order short description (display on form) R R
orderId String Order identifier (must be unique) R R R

(max 40)
channel string Merchant business code R R
sourceOfFundsType string Always be CARD R R
dataKey string Secured key for communication with Napas R R R
12
napasKey string Secured key for data encryption R R R
serviceCode string Reserved for future use O O
language string Napas Hosted Form display language O O O
vi: Vietnamese
en: English
*R: field must be presented
*RE: field must be presented and have the same value as in Data Key transaction request.
*O: field is optional
13
3.4 Receive response from Napas
Merchant will receive response in 2 separate ways:
- Form Submit: result will be submitted into the URL in action parameter, Merchant
uses this result to display result page to customer.
The result will be included in napasResult parameter.

- IPN: result will be POST into the IPN URL that Merchant has registered with Napas.
Merchant uses this result to process backend works.
The result will be in requestBody.

* Napas only sends result via IPN in case of the transaction had been succeeded.
** Merchant should be aware of duplicate records of success transactions when receiving both
Form Submit and IPN results.
Response fields details

Field name Field Description
Type
data string A result string encoded in base64
checksum string Checksum of the data, calculated by sha256(data + client_secret), use to verify the data string is from Napas.
Merchant decode the data string to obtain result in JSON format

Field name Field Description
Type
tokenResult Result of the Create Token transaction
tokenResult.result string A system-generated high level overall result of the operation
FAILURE: The operation was declined or rejected by the gateway, acquirer or issuer
tokenResult.respons string Response data group

e
tokenResult.token string Generated token
tokenResult.card Card data group
14
tokenResult.card.bra string The brand name used to describe the card that is recognized and accepted globally.
nd
tokenResult.card.ex Expiry info data group

piry
tokenResult.card.ex string Month, as shown on the card.

piry.month
tokenResult.card.ex string Year, as shown on the card.

piry.year
tokenResult.card.iss string The issuer of the card, if known.

uer
tokenResult.card.iss string Issuer code of local bank.

uerCode
tokenResult.card.na string The cardholder's name as printed on the card

meOnCard
tokenResult.card.iss string Card issue date, shown on the card.

ueDate
MMYY format.
tokenResult.card.nu string Credit card number as printed on the card, masked.

mber
tokenResult.card.sc string The organization that owns a card brand and defines operating regulations for its use.
heme
tokenResult.card.sta string Only returns if enable3DSecure is set to true in the request

tus3ds
true: card is enrolled with 3DS
false: card is not enrolled with 3DS
tokenResult.deviceI string Customer identifier

d
paymentResult Result of the Payment transaction, refer to 4.1 Pay transaction, response message for details.
15
4 Direct API Implementation
4.1 Pay / Authorize / Capture / Void / Refund (for International Card
Processing)
Refund Domestic transaction (for Domestic Card Processing)
Merchant use the following information to integrate with Napas system:
URL https://dps-
staging.napas.com.vn/api/rest/version/1/merchant/{merchantId}/order/{orderId}/tr
ansaction/{transactionId}
HTTP Method PUT

Validation orderId and transactionId must be unique, length must be less than 40 chars.
Fields detail

Message Message
apiOperation R R PAY: Authorise the payment and transfer funds.
AUTHORIZE: Request to obtain an authorization for a proposed funds transfer.
CAPTURE: Request to capture funds previously reserved by an authorization
VOID: Request to void a previous transaction
REFUND: Request to refund previously captured funds to the payer
REFUND_DOMESTIC: Request to refund previously captured funds to the
payer (for previous domestic transaction)
authorizationResponse Authorization response data group.
Information on fields returned by some acquirers for an authorization or pay
transaction.
authorizationResponse. Data can C CSC Incorrect Indicator.
cardSecurityCodeError consist of any An indicator, provided by the Issuer in the authorization response, to identify the
characters
presence of an invalid card security code (CSC). If there is an error, the Issuer
will respond with the 1-byte CSC Error Code (Y).
authorizationResponse. Data can C Indicates if the card used is a commercial card
commercialCard consist of any
characters
authorizationResponse. Data can C Indicates the type of commercial card as returned by the card issuer
CommercialCardIndicat consist of any
or characters
authorizationResponse. Data can C The local date, in MMDD format, on which the transaction occurred.
date consist of any
characters
authorizationResponse. Data must C The date for the Authorization as returned by the financial network.
financialNetworkDate comply with
16
ISO 8601 For transactions processed via the MasterCard Network this is the MasterCard
extended date Network Reference Date.
format, yyyy-
mm-dd
authorizationResponse. Data can C Identifies the type of Card Transaction sent to Card Acceptor.
processingCode consist of any
characters
authorizationResponse.r Data can C The response code which indicates the status of the transaction
esponseCode consist of any
characters
authorizationResponse.r Data can C Textual description of the acquirer response code for displaying on terminals
esponseMessage consist of any
characters
authorizationResponse.r Data can C The ACI (Authorization Characteristics Indicator) returned by the issuer
eturnAci consist of any
characters
authorizationResponse.s Data can C The System Trace Audit Number is assigned by a transaction originator to assist
tan consist of any in identifying a Card Transaction.
characters The trace number remains unchanged for the life of the Card Transaction.
authorizationResponse.t Data can C The local time, in HHMMSS format, during which the transaction occurred
ime consist of any
characters
authorizationResponse. Data can C The unique identifier for the transaction returned by the issuer
TransactionIdentifier consist of any
characters
authorizationResponse. Data can C The validation code returned by the issuer.
validationCode consist of any This value must be stored to be sent with the capture transaction.
characters
correlationId Data can O C A transient identifier for the request, that can be used to match the response to
consist of any the request
characters The value provided is not validated, does not persist in the gateway, and is
returned as provided in the response to the request
customer Customer data group.
Information associated with the customer's source of transaction
customer.email Ensures that O C The email address of the customer.
the email The field format restriction ensures that the email address is longer than 3
address is
characters and adheres to a generous subset of valid RFC 2822 email addresses.
longer than 3
characters and
adheres to a
generous
subset of
valid RFC
2822 email
addresses
customer.firstName Data can O C The payer's first name
consist of any
characters
customer.lastName Data can O C The payer's last or surname
consist of any
characters
17
customer.mobilePhone Data can O C The contact person's mobile phone or cell phone number.
consist of any
characters
customer.phone Data can O C The phone number of the person to whom the order is being billed
consist of any
characters
device Device information data group.
Information associated with the device's source of transaction.
device.ipAddress Data can O C The IP address of the computer used by the customer, in nnn.nnn.nnn.nnn
consist of any format
characters
merchantId R Id of merchant
order Order data group.
Information about the order associated with this transaction
order.amount Data is a R R The total amount for the order.
string that
consists of the
characters 0-9
and '.' and
represents a
valid decimal
number
order.creationTime An instant in R The timestamp indicating the time the gateway considers the order to have been
time created
expressed in
ISO8601 date
+ time format
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
order.reference Data can O C The identifier of the order.
consist of any For example, a shopping cart number, an order number, or an invoice number.
characters
order.currency Data must R R The currency of the order expressed as an ISO 4217 alpha code, e.g. USD
consist of the
characters A-
Z
order.id Data can R A unique identifier for this order to distinguish it from any other order you
consist of any create.
characters
Use this identifier when referring to this order in subsequent transactions and in
retrieval operations.
This value must be unique for every order created by your merchant profile.
order.totalAuthorizedA A sequence of R The amount that has been successfully authorized for this order.
mount digits 0-9 Max value:1000000000000
separated by a
'.' as a Min value: 0
decimal
indicator. maximum post-decimal digits: 3
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
18
order.totalCapturedAm A sequence of R The amount that has been successfully captured for this order
ount digits 0-9 Max value:1000000000000
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
order.totalRefundedAm R The amount that has been successfully refunded for this order
ount Max value:1000000000000
Min value: 0
maximum post-decimal digits: 3
redirectUrl Data can C The URL to which you want to redirect the payer after completing the payer
consist of any authentication process.
characters
* Required in Verify Card transaction, which uses card information
response Response data group
response.acquirerCode Data consists C Value as generated by the acquirer that summarizes the success or otherwise of
of ASCII the proposed operation
characters
response.acquirerMessa Data consists C The response from the acquirer in the text form.
ge of ASCII This field is used in addition to response.acquirerCode for some acquirers where
characters
additional information needs to be communicated. For example, contact details
to allow the merchant to contact the issuer directly to seek authorisation for the
transaction.
response.cardSecurityC Response CSC group

ode
response.cardSecurityC Data consists C The acquirer CSC response code generated by the card issuing institution
ode.acquirerCode of ASCII
characters
response.cardSecurityC C The card security code result generated to indicate whether the data supplied
ode.gatewayCode matches the data held by the cardholder's issuing bank
MATCH: Valid or matched.
NOT_PRESENT: Merchant indicated CSC not present on card.
NOT_PROCESSED: Not processed.
NOT_SUPPORTED: Card issuer is not registered and/or certified
NO_MATCH: Invalid or not matched.
response.cardholderVer Response cardholder verification data group.
ification
response.cardholderVer Response cardholder verification detailed verification data group.
ification. Results of the additional verification checks where an acquirer offers advanced
detailedVerification[n]
cardholder verification and the data has been supplied in the Verify request.
response.cardholderVer C The result returned after the specified data type has been verified by the acquirer
ification. Value must be a member of the following list. The values are case sensitive.
detailedVerification[n].
MATCHED: Data provided by cardholder matches record held by the
gatewayCode
cardholder's issuing bank.
19
NOT_MATCHED: Data provided by cardholder does NOT match record held
by the cardholder's issuing bank.
NOT_PROVIDED: Verification could not be performed as data not provided.
NOT_CHECKED: Unable to perform verification checks on data provided.
SERVICE_NOT_SUPPORTED: Service currently not supported by acquirer or
merchant
SERVICE_NOT_AVAILABLE_RETRY: Issuer system is unavailable. Retry
can be attempted
response.gatewayCode R Summary of the success or otherwise of the proposed operation
APPROVED: Transaction Approved
UNSPECIFIED_FAILURE: Transaction could not be processed
DECLINED: Transaction declined by issuer
TIMED_OUT: Response timed out
EXPIRED_CARD: Transaction declined due to expired card
INSUFFICIENT_FUNDS: Transaction declined due to insufficient funds
ACQUIRER_SYSTEM_ERROR: Acquirer system error occurred processing
the transaction
SYSTEM_ERROR: Internal system error occurred processing the transaction
NOT_SUPPORTED: Transaction type not supported
DECLINED_DO_NOT_CONTACT: Transaction declined - do not contact
issuer
ABORTED: Transaction aborted by payer
BLOCKED: Transaction blocked due to Risk or 3D Secure blocking rules
CANCELLED: Transaction cancelled by payer
DEFERRED_TRANSACTION_RECEIVED: Deferred transaction received and
awaiting processing
REFERRED: Transaction declined - refer to issuer
AUTHENTICATION_FAILED: 3D Secure authentication failed
INVALID_CSC: Invalid card security code
LOCK_FAILURE: Order locked - another transaction is in progress for this
order
SUBMITTED: Transaction submitted - response has not yet been received
NOT_ENROLLED_3D_SECURE: Card holder is not enrolled in 3D Secure
PENDING: Transaction is pending
EXCEEDED_RETRY_LIMIT: Transaction retry limit exceeded
DUPLICATE_BATCH: Transaction declined due to duplicate batch
DECLINED_AVS: Transaction declined due to address verification
DECLINED_CSC: Transaction declined due to card security code
DECLINED_AVS_CSC: Transaction declined due to address verification and
card security code
DECLINED_PAYMENT_PLAN: Transaction declined due to payment plan
APPROVED_PENDING_SETTLEMENT: Transaction Approved - pending
batch settlement
PARTIALLY_APPROVED: The transaction was approved for a lesser amount
than requested. The approved amount is returned in
order.totalAuthorizedAmount.
UNKNOWN: Response unknown
result R A system-generated high level overall result of the operation
issuer
20
serviceCode O Reserved for future use
sourceOfFunds Source of fund data group.
Information about the payment type selected by the payer for this payment and
the source of the funds.
Depending on the payment type the source of the funds can be a debit or credit
card, bank account, or account with a browser payment provider (such as
PayPal).
sourceOfFunds.provide Source of fund provided data group.
d Information about the source of funds when it is directly provided (as opposed to
via a token or session).
sourceOfFunds.provide Source of fund provided card data group.

d.card Details as shown on the card.
sourceOfFunds.provide O R The brand name used to describe the card that is recognized and accepted
d.card.brand globally.
For many major card types this will match the scheme name. In some markets, a
card may also be co-branded with a local brand that is recognized and accepted
within its country/region of origin (see card.localBrand).
You may use this information to support surcharging decisions. This information
is gathered from 3rd party sources and may not be accurate in all circumstances.
AMEX: American Express
DINERS_CLUB: Diners Club
DISCOVER: Discover
JCB: JCB (Japan Credit Bureau)
MAESTRO: Maestro
MASTERCARD: MasterCard
VISA: Visa
UATP: UATP (Universal Air Travel Plan)
LOCAL_BRAND_ONLY: The card does not have a global brand.
UNKNOWN: The brand of the card used in the transaction could not be
identified
sourceOfFunds.provide Expiry info data group

d.card.expiry Expiry date, as shown on the card.
sourceOfFunds.provide Data is a C R Month, as shown on the card.
d.card.expiry.month number Months are numbered January=1, through to December=12.
between 1 and
12
represented as
a string.
sourceOfFunds.provide Data is a C R Year, as shown on the card.
d.card.expiry.year string that The Common Era year is 2000 plus this value.
consist of the
characters 0-
9.
sourceOfFunds.provide Data can C The issuer of the card, if known.
d.card.issuer consist of any WARNING: This information may be incorrect or incomplete – use at your own
characters
risk.
sourceOfFunds.provide Data is a O C For the local purpose

d.card.issuerCode string that Issuer code of local bank
consist of the
characters 0-9
21
sourceOfFunds.provide Data can C C The cardholder's name as printed on the card
d.card.nameOnCard consist of any
characters
sourceOfFunds.provide Data is a C C Card issue date, shown on the card.
d.card.issueDate string that MMYY format.
consist of the
characters 0-9
sourceOfFunds.provide Data is a C O Credit card number as printed on the card.
d.card.number string that
consist of the
characters 0-9
sourceOfFunds.provide R The organization that owns a card brand and defines operating regulations for its
d.card.scheme use.
The card scheme also controls authorization and settlement of card transactions
among issuers and acquirers.
DISCOVER: Discover
VISA: Visa
OTHER: The scheme of the card used in the transaction could not be identified.
sourceOfFunds.provide Data may C The code used to indicate the existence of the Card Security Code value
d.card. consist of the
securityCodePresence characters 0-
9, a-z, A-Z
sourceOfFunds.provide Data is a C O Card verification code, as printed on the back or front of the card
d. string that
card.securityCode consist of the
characters 0-9
sourceOfFunds.token Data may C C Uniquely identifies a card and associated details
consist of the
characters 0-
9, a-z, A-Z
sourceOfFunds.type R C The payment method your payer has chosen for this payment.
CARD: The payer selected to pay using a credit or debit card. The payer's card
details must be provided.
In case of token using, please send this parameter with value CARD.
timeOfRecord An instant in C Transaction Date.

time The date when the transaction happened.The time the gateway considers the
expressed in
operation to have occurred. The gateway uses timeOfRecord as a point-in-time
ISO8601 date
+ time format value for operations such as sorting, billing, and reporting.
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
transaction Transaction data group.
Information about this transaction.
22
transaction.acquirer Acquirer data group.
Information about this transaction
transaction.acquirer.id Data can R The ID for the acquirer used to process the transaction
consist of any
characters
transaction.acquirer.mer Data can C The Acquirer Merchant Identifier (also known as Card Acceptor Identification
chantId consist of any Code (CAIC)) is an identifier allocated to you by your acquirer.
characters
transaction.acquirer.tim Data can C The time the transaction was processed, as returned by the acquirer
e consist of any Not returned by most acquirers
characters
transaction.acquirer.tran Data can C Identifier used by the acquirer to identify the transaction.
sactionId consist of any This identifier may be used by the acquirer in settlement reports.
characters
transaction.amount A sequence of C R The total amount for the transaction
digits 0-9 maximum value: 1000000000000
separated by a
minimum value: 0
'.' as a
decimal maximum post-decimal digits: 3
indicator. *Required in Capture / Refund transaction
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
transaction.authorizatio Data consists C Value generated by the issuing bank in response to a proposal to transfer funds
nCode of ASCII
characters
transaction.currency Data must C R The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD
consist of the *Required in Capture / Refund transaction
characters A-
Z
transaction.id Data can R Unique identifier for this transaction to distinguish it from any other transactions
consist of any on the order
characters
transaction.receipt Data consists C The Reference Retrieval Number (RRN) is a unique number generated by the
of ASCII acquirer for a specific merchant transaction.
characters
The RRN can be used to retrieve the transaction data from the acquirer.
transaction.reference Data can C An optional identifier for this transaction.

consist of any
characters
transaction.requestedA A sequence of C If the transaction was partially approved
mount digits 0-9 (response.gatewayCode=PARTIALLY_APPROVED), this field contains the
separated by a
originally requested amount.
'.' as a
decimal The transaction amount (transaction.amount) and order amount (order.amount)
indicator. are both set to the actually approved amount.
Leading and
trailing zeroes
are optional. maximum value: 1000000000000
If the minimum value: 0
fractional part maximum post-decimal digits: 3
is zero, the '.'
and following
23
zero(es) can
be omitted
transaction.targetTransa Data can C C The identifier for the transaction you wish to void or refund.
ctionId consist of any That is the {transactionId} URL field for REST and the transaction.id field for
characters
NVP.
*Required in Void transaction
transaction.type R Indicates the type of action performed on the order.

AUTHORIZATION: Authorization
AUTHORIZATION_UPDATE: Authorization Update
BALANCE_ENQUIRY: Balance Enquiry
CAPTURE: Capture
CREDIT_PAYMENT: Credit Payment
ORDER_AGREEMENT: Order Agreement
PRE_AUTHORIZATION: Pre-Authorization
PAYMENT: Payment (Purchase)
REFUND: Refund
VOID_AUTHORIZATION: Void Authorization
VOID_CAPTURE: Void Capture
VOID_CREDIT_PAYMENT: Void Credit Payment
VOID_PAYMENT: Void Payment
VOID_REFUND: Void Refund
VERIFICATION: Verification
REFUND_REQUEST: Refund Request
OTHER: Other transaction types
transaction.otp Data consist O O One time password, use for local purpose
of a-z, A-Z,
0-9 characters
transaction.typeOfVerif C C Indicates the type of verification performed with debit/atm card.
ication Value must be a member of the following list. The values are case sensitive.
OTP: in this case, transaction.otp will contain the OTP value sent to payer
(payer inputs this value).
PIN: in this case, transaction.otp will contains the PIN value (payer inputs this
value).
channel Data consist R O The system uses MCC clarification from standard industry. Proper values will
0-9 characters be sent to merchant.
version Data can C The Web Services API version that you submitted the request in
consist of any
characters
24
4.2 Pay with 3DSecure transaction
URL https://dps-
ansaction/{transactionId}/3DSecureId/{3DSecureId}
HTTP Method PUT

Validation orderId, transactionId and 3DSecureId must be unique, length must be less than 40
chars.
Please refer to Appendix B, Pay with 3DSecure transaction flow to get more information of
how the transaction is being processed.
Fields detail
Message Message
apiOperation R R PAY_WITH_3DS: Authorise the payment and transfer funds, which includes a
3DSecure process that identify cardholder.
3DSecure Information on 3DSecure fields.
3DSecure.authenticatio A collection of parameters required to build the HTML form that is redirected
nRedirect to the ACS.
3DSecure.authenticatio The simple field is the response returned to those merchants who have chosen
nRedirect.simple the simple option for form submission.
3DSecure.authenticatio Data can C The generated form to post to the cardholder’s browser.
nRedirect.simple.htmlB consist of any
odyContent characters
3DSecure.authenticatio Data can R The URL to which you want to redirect the payer after completing the payer
nRedirect.responseUrl consist of any authentication process.
characters
3Dsecure.summaryStat Data can C The summarized response from the card issuer and the payment gateway
us consist of any indicating the overall status of the attempt to authenticate the cardholder.
characters
3DSecure.xid A unique transaction identifier generated by the Payment Gateway on behalf of
the merchant to identify the 3DS transaction.
3DSecureId Data can C A unique identifier supplied by the merchant for the authentication.
consist of any
characters
transaction.
25
cardSecurityCodeError consist of any An indicator, provided by the Issuer in the authorization response, to identify
characters
the presence of an invalid card security code (CSC). If there is an error, the
Issuer will respond with the 1-byte CSC Error Code (Y).
characters
or characters
date consist of any
characters
financialNetworkDate comply with For transactions processed via the MasterCard Network this is the MasterCard
ISO 8601
Network Reference Date.
extended date
format, yyyy-
mm-dd
characters
characters
characters
characters
authorizationResponse.s Data can C The System Trace Audit Number is assigned by a transaction originator to
tan consist of any assist in identifying a Card Transaction.
ime consist of any
characters
characters
characters
the email
address is
26
longer than 3 The field format restriction ensures that the email address is longer than 3
characters and characters and adheres to a generous subset of valid RFC 2822 email addresses.
adheres to a
generous
subset of
valid RFC
2822 email
addresses
consist of any
characters
consist of any
characters
consist of any
characters
consist of any
characters
characters
string that
consists of the
characters 0-9
and '.' and
represents a
valid decimal
number
order.creationTime An instant in R The timestamp indicating the time the gateway considers the order to have
time been created
expressed in
ISO8601 date
+ time format
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
characters
consist of the
characters A-
Z
characters
27
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
Min value: 0
response.3DSecure The response code which indicates the status.
response.3DSecure.gate C The detailed response from the payment gateway to indicate the status of the
wayCode 3DS authentication.
characters
ge of ASCII This field is used in addition to response.acquirerCode for some acquirers
characters
where additional information needs to be communicated. For example, contact
details to allow the merchant to contact the issuer directly to seek authorisation
for the transaction.

ode
characters
28
ification
response.cardholderVer C The result returned after the specified data type has been verified by the
ification. acquirer
gatewayCode
merchant
can be attempted
the transaction
issuer
DEFERRED_TRANSACTION_RECEIVED: Deferred transaction received
and awaiting processing
order
29
card security code
batch settlement
issuer
PayPal).
d Information about the source of funds when it is directly provided (as opposed
to via a token or session).

sourceOfFunds.provide O R The brand name used to describe the card that is recognized and accepted
For many major card types this will match the scheme name. In some markets,
a card may also be co-branded with a local brand that is recognized and
accepted within its country/region of origin (see card.localBrand).
You may use this information to support surcharging decisions. This
information is gathered from 3rd party sources and may not be accurate in all
circumstances.
DISCOVER: Discover
MAESTRO: Maestro
VISA: Visa
identified
30
sourceOfFunds.provide Data is a C R Month, as shown on the card.
between 1 and
12
represented as
a string.
sourceOfFunds.provide Data is a C R Year, as shown on the card.
consist of the
characters 0-
9.
d.card.issuer consist of any WARNING: This information may be incorrect or incomplete – use at your
characters
own risk.
sourceOfFunds.provide Data is a O C For the local purpose

consist of the
characters 0-9
sourceOfFunds.provide Data can O C The cardholder's name as printed on the card
characters
sourceOfFunds.provide Data is a O C Card issue date, shown on the card.
consist of the
characters 0-9
sourceOfFunds.provide Data is a O O Credit card number as printed on the card.
consist of the
characters 0-9
sourceOfFunds.provide R The organization that owns a card brand and defines operating regulations for
d.card.scheme its use.
DISCOVER: Discover
VISA: Visa
OTHER: The scheme of the card used in the transaction could not be
identified.
9, a-z, A-Z
sourceOfFunds.provide Data is a O O Card verification code, as printed on the back or front of the card
d. string that
card.securityCode consist of the
characters 0-9
31
sourceOfFunds.token Data may O C Uniquely identifies a card and associated details
consist of the
characters 0-
9, a-z, A-Z
sourceOfFunds.type C The payment method your payer has chosen for this payment.

expressed in
ISO8601 date
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
consist of any
characters
characters
characters
characters
transaction.amount A sequence of R The total amount for the transaction
separated by a
minimum value: 0
'.' as a
indicator.
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
nCode of ASCII
characters
transaction.currency Data must R The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD
consist of the
characters A-
Z
32
transaction.id Data can R Unique identifier for this transaction to distinguish it from any other
consist of any transactions on the order
characters
characters

consist of any
characters
separated by a
'.' as a
Leading and
trailing zeroes
is zero, the '.'
and following
zero(es) can
be omitted
transaction.targetTransa Data can O C The identifier for the transaction you wish to void or refund.
characters
NVP.

CAPTURE: Capture
REFUND: Refund
of a-z, A-Z,
0-9 characters
value).
33
language O O
Optional.
Value is sensitive, and must be one of the following list:
- vn: Vietnamese language is used in web UI. This is default value in
case of this field is not sent to Napas, or value is not in approved list.
- en: English language is used in web UI
consist of any
characters
Note for this transaction:

Base on the status of the card’s 3DSecure enrollment, merchant can receive 2 different results
as follow:
 If card is enrolled with 3DS, merchant will receive SUCCESS result with
htmlBodyContent field – which includes a HTML snippet used to send customer to
Issuer Bank’s Access Control Server in order to authorize the cardholder.
After the customer finish the purchase, merchant will receive response in 2 ways:
o Form Submit: result will be submitted into the URL in
3DSecure.authenticationRedirect.responseUrl parameter, Merchant uses this
result to display result page to customer.
The result will be in napasResult parameter.

o IPN: result will be POST into the IPN URL that Merchant has registered with
Napas. Merchant uses this result to process backend works.
The result will be in requestBody.

Data structure of the response, please refer to 3.4 Receive response from Napas
* Napas always sends result via IPN once transaction is completed, regardless of
transaction result.
** Merchant should be aware of duplicate records of success transaction when
receiving both Form Submit and IPN result
 If card is not enrolled with 3DS, merchant will receive the final result of the payment
transaction.
34
4.3 Purchase OTP transaction – integrate with Napas Hosted Checkout
URL https://dps-
ansaction/{transactionId}
HTTP Method PUT

Validation orderId and transactionId must be unique, length must be less than 40 chars.
Fields detail
Message Message
apiOperation R R PURCHASE_OTP: Authorise the payment and transfer funds.
Verify card information (for debit card of local bank).
transaction.
cardSecurityCodeError consist of any An indicator, provided by the Issuer in the authorization response, to identify
characters
the presence of an invalid card security code (CSC). If there is an error, the
Issuer will respond with the 1-byte CSC Error Code (Y).
characters
or characters
date consist of any
characters
ISO 8601
extended date
format, yyyy-
mm-dd
characters
characters
35
characters
characters
authorizationResponse.s Data can C The System Trace Audit Number is assigned by a transaction originator to
tan consist of any assist in identifying a Card Transaction.
ime consist of any
characters
characters
characters
address is
longer than 3
characters and
adheres to a
generous
subset of
valid RFC
2822 email
addresses
consist of any
characters
consist of any
characters
consist of any
characters
consist of any
characters
characters
36
string that
consists of the
characters 0-9
and '.' and
represents a
valid decimal
number
order.creationTime An instant in R The timestamp indicating the time the gateway considers the order to have
time been created
expressed in
ISO8601 date
+ time format
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
characters
consist of the
characters A-
Z
characters
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
37
zero(es) can
be omitted
Min value: 0
characters
ge of ASCII This field is used in addition to response.acquirerCode for some acquirers
characters
where additional information needs to be communicated. For example, contact
details to allow the merchant to contact the issuer directly to seek authorisation
for the transaction.

ode
characters
ification
response.cardholderVer C The result returned after the specified data type has been verified by the
ification. acquirer
gatewayCode
merchant
can be attempted
38
the transaction
issuer
DEFERRED_TRANSACTION_RECEIVED: Deferred transaction received
and awaiting processing
order
card security code
batch settlement
issuer
PayPal).
sourceOfFunds.token Data may R C Uniquely identifies a card and associated details
consist of the
characters 0-
9, a-z, A-Z
sourceOfFunds.type R C The payment method your payer has chosen for this payment.
39

expressed in
ISO8601 date
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
consist of any
characters
characters
characters
characters
separated by a
minimum value: 0
'.' as a
indicator.
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
nCode of ASCII
characters
consist of the
characters A-
Z
transaction.id Data can R Unique identifier for this transaction to distinguish it from any other
consist of any transactions on the order
characters
characters
40
consist of any
characters
separated by a
'.' as a
Leading and
trailing zeroes
is zero, the '.'
and following
zero(es) can
be omitted
transaction.targetTransa Data can O C The identifier for the transaction you wish to void or refund.
characters
NVP.

CAPTURE: Capture
REFUND: Refund
of a-z, A-Z,
0-9 characters
value).
consist of any
characters
inputParameters Input parameters data group.
41
inputParameters.clientI Data can R IP of the customer client
P consist of any
characters
inputParameters.deviceI Data can R Customer identifier, this will be returned to merchant after processing
d consist of any transaction.
characters
inputParameters.enviro Data can R WebApp: use to integrate on Web Applications
nment consist of any MobileApp: use to integrate on Mobile Applications
characters
inputParameters.cardSc Data can R CreditCard: use in case of international cards.
heme consist of any AtmCard: use in case of domestic cards
characters
inputParameters.enable R Supports 3DSecure for authorizing cardholder when using CreditCard.
3DSecure
true: enable 3DSecure flow
false: disable 3DSecure flow
The integration process and response is the same as 3. Hosted Checkout Implementation.
Please refer to Integration Guide Document for further details.
42
4.4 Retrieve Order transaction
URL (for https://dps-

international staging.napas.com.vn/api/rest/version/1/merchant/{merchantId}/order/{orderId}/i
card retrieval) nternational
URL(for https://dps-
domestic card staging.napas.com.vn/api/rest/version/1/merchant/{merchantId}/order/{orderId}/d
retrieval) omestic
HTTP Method GET

Fields detail
Message Message
apiOperation O R RETRIEVE: Request to retrieve the details of a transaction
transaction.
cardSecurityCodeError consist of any An indicator, provided by the Issuer in the authorization response, to identify the
characters
presence of an invalid card security code (CSC). If there is an error, the Issuer
will respond with the 1-byte CSC Error Code (Y).
characters
commercialCardIndicat consist of any
or characters
date consist of any
characters
ISO 8601
extended date
format, yyyy-
mm-dd
characters
43
characters
characters
characters
authorizationResponse.s Data can C The System Trace Audit Number is assigned by a transaction originator to assist
tan consist of any in identifying a Card Transaction.
ime consist of any
characters
transactionIdentifier consist of any
characters
characters
consist of the request
any The value provided is not validated, does not persist in the gateway, and is
characters returned as provided in the response to the request

customer.email Ensures that C The email address of the customer.
address is
longer than 3
characters and
adheres to a
generous
subset of
valid RFC
2822 email
addresses
customer.firstName Data can C The payer's first name
consist of any
characters
customer.lastName Data can C The payer's last or surname
consist of any
characters
customer.mobilePhone Data can C The contact person's mobile phone or cell phone number.
consist of any
characters
customer.phone Data can C The phone number of the person to whom the order is being billed
consist of any
characters
44
device.ipAddress Data can C The IP address of the computer used by the customer, in nnn.nnn.nnn.nnn
characters
order.amount Data is a R The total amount for the order.
string that
consists of the
characters 0-9
and '.' and
represents a
valid decimal
number
order.creationTime An instant in R The timestamp indicating the time the gateway considers the order to have been
time created
expressed in
ISO8601 date
+ time format
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
order.reference Data can C The identifier of the order.
characters
order.currency Data must R The currency of the order expressed as an ISO 4217 alpha code, e.g. USD
consist of the
characters A-
Z
characters
separated by a
decimal
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
separated by a
decimal
Leading and
trailing zeroes
are optional.
45
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
Min value: 0
characters
ge of ASCII This field is used in addition to response.acquirerCode for some acquirers where
characters
additional information needs to be communicated. For example, contact details
to allow the merchant to contact the issuer directly to seek authorisation for the
transaction.

ode
characters
ification
response.cardholderVer C The result returned after the specified data type has been verified by the acquirer
ification. Value must be a member of the following list. The values are case sensitive.
gatewayCode
merchant
can be attempted
46
the transaction
issuer
DEFERRED_TRANSACTION_RECEIVED: Deferred transaction received and
awaiting processing
order
card security code
batch settlement
issuer
PayPal).
d Information about the source of funds when it is directly provided (as opposed to
via a token or session).
47
sourceOfFunds.provide R The brand name used to describe the card that is recognized and accepted
For many major card types this will match the scheme name. In some markets, a
card may also be co-branded with a local brand that is recognized and accepted
within its country/region of origin (see card.localBrand).
You may use this information to support surcharging decisions. This information
is gathered from 3rd party sources and may not be accurate in all circumstances.
DISCOVER: Discover
MAESTRO: Maestro
VISA: Visa
identified

sourceOfFunds.provide Data is a R Month, as shown on the card.
between 1 and
12
represented as
a string.
sourceOfFunds.provide Data is a R Year, as shown on the card.
consist of the
characters 0-
9.
d.card.issuer consist of any WARNING: This information may be incorrect or incomplete – use at your own
characters
risk.
sourceOfFunds.provide Data is a C For the local purpose

consist of the
characters 0-9
sourceOfFunds.provide Data can C The cardholder's name as printed on the card
characters
sourceOfFunds.provide Data is a C Card issue date, shown on the card.
consist of the
characters 0-9
sourceOfFunds.provide Data is a O Credit card number as printed on the card.
consist of the
characters 0-9
48
sourceOfFunds.provide R The organization that owns a card brand and defines operating regulations for its
d.card.scheme use.
DISCOVER: Discover
VISA: Visa
OTHER: The scheme of the card used in the transaction could not be identified.
9, a-z, A-Z
sourceOfFunds.provide Data is a O Card verification code, as printed on the back or front of the card
d.card.securityCode string that
consist of the
characters 0-9
sourceOfFunds.token Data may C Uniquely identifies a card and associated details
consist of the
characters 0-
9, a-z, A-Z
sourceOfFunds.type C The payment method your payer has chosen for this payment.

expressed in
ISO8601 date
- "YYYY-
MM-
DDThh:mm:s
s.SSSZ"
consist of any
characters
characters
characters
49
characters
separated by a
minimum value: 0
'.' as a
indicator.
Leading and
trailing zeroes
are optional.
If the
fractional part
is zero, the '.'
and following
zero(es) can
be omitted
nCode of ASCII
characters
consist of the
characters A-
Z
transaction.id Data can R Unique identifier for this transaction to distinguish it from any other transactions
consist of any on the order
characters
characters

consist of any
characters
separated by a
'.' as a
Leading and
trailing zeroes
is zero, the '.'
and following
zero(es) can
be omitted
transaction.targetTransa Data can C The identifier for the transaction you wish to void or refund.
characters
NVP.

CAPTURE: Capture
50
REFUND: Refund
transaction.otp Data consist O One time password, use for local purpose
of a-z, A-Z,
0-9 characters
channel Data consist O The system uses MCC clarification from standard industry. Proper values will
consist of any
characters
51
4.5 Delete Token transaction
URL https://dps-
staging.napas.com.vn/api/rest/version/1/merchant/{merchantId}/token/{token}
HTTP Method DELETE

Fields detail
Message Message
apiOperation O R DELETE_TOKEN
merchantId Data may O O Id of merchant
consist of the
characters 0-
9, a-z, A-
token Data may O O Uniquely identifies a card and associated details
consist of the
characters 0-
9, a-z, A-Z
issuer
52
4.6 Error parameters
In case of error in validation of the request, the following fields will be send back to
merchant:
Field name Field type Response Description
Message
error.cause R Broadly categorizes the cause of the error.
For example, errors may occur due to invalid requests or internal system failures.
REQUEST_REJECTED: The request was rejected due to security reasons such as
firewall rules, expired certificate, etc.
INVALID_REQUEST: The request was rejected because it did not conform to the API
protocol.
SERVER_FAILED: There was an internal system failure.
SERVER_BUSY: The server did not have enough resources to process the request at
the moment.
error.explanation Data may O Textual description of the error based on the cause.
consist of the This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
characters
error.field Data may O Indicates the name of the field that failed validation
consist of the This field is returned only if the cause is INVALID_REQUEST and a field level
characters
validation error was encountered.
error.supportCode O Indicates the code that helps the support team to quickly identify the exact cause of the
error.
This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
error.validationType O Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level
validation error was encountered.
INVALID: The request contained a field with a value that did not pass validation.
MISSING: The request was missing a mandatory field.
UNSUPPORTED: The request contained a field that is unsupported.
result A system-generated high level overall result of the operation.

ERROR: The operation resulted in an error and hence cannot be processed.
53
5 Response Code
5.1 International Card Process
result response.gatewayCode / error.cause Description
SUCCESS Transaction is approved
SUCCESS CARD_ENROLLED Authentication is successful
AUTHENTICATION_SUCCESSFUL Authentication is successful
OTHER_ERROR Transaction failed
DECLINED Transaction is declined by ISS
EXPIRED_CARD Card has expired
INSUFFICIENT_FUNDS Insufficient funds to make payment
TXN_NOT_ALLOWED Transaction failed
CANCELLED Transaction is cancelled
REJECTED_BY_RISK_MANAGEMENT Transaction is rejected by risk management.
REFERRED Transaction is declined by ISS
REJECTED_BY_AVS Transaction is declined by ISS
REJECTED_BY_CSC Transaction is declined by ISS
FAILURE REJECTED_BY_CSC_AVS Transaction is declined by ISS
NOT_ENROLLED Authentication is not available
ENROLLMENT_STATUS_UNDETERMINED Authentication failed
NO_AUTHENTICATION_DATA Authentication failed
AUTHENTICATION_ATTEMPTED Authentication failed
AUTHENTICATION_NOT_AVAILABLE Authentication failed
AUTHENTICATION_FAILED Authentication failed
NOT_AUTHENTICATED Authentication failed
NO_3DS_DATA Authentication failed
NO_CAVV_AAV Rejected due to no CAVV/AAV
RMS_REJECT Rejected by RMS
ERROR INVALID_REQUEST Transaction failed
INVALID_CSC Invalid card information
54
EXPIRED_SESSION Session has expired
INVALID_CARD Invalid card format
CUSTOMER_CANCELLED Customer cancelled the payment
BLACKLISTED_BIN Transaction is rejected by risk management.
BLACKLISTED_IP Transaction is rejected by risk management.
BIN_VELOCITY Transaction is rejected by risk management.
IP_VELOCITY Transaction is rejected by risk management.
VALUE_EXCEEDED_LIMIT Transaction is rejected by risk management.
PENDING PENDING Transaction is pending
55
5.2 Domestic Card Process
result response.gatewayCode / error.cause Description
SUCCESS APPROVED Transaction is approved
LOCKED_CARD Card is locked
INVALID_CARDINFO Invalid card information
EXPIRED_CARD Card has expired
TIMED_OUT No reply from bank
BANK_ERROR Bank system/communication error
INSUFFICIENT_FUNDS Insufficient funds to make payment
INVALID_CHECKSUM Checksum error
TRANSACTION_NOT_SUPPORTED Unsupported transaction type
PENDING_FOR_OTP Card information has been verified
CARD_LIMIT_EXCEEDED Transaction exceeds daily limit set by bank
UNREGISTED_CARD Card not registered for online payment
INVALID_OTP Invalid OTP
FAILURE INVALID_CARDNAME Invalid cardholder name
INVALID_CARDNO Invalid card number
INVALID_ISSDATE Invalid issue date
INVALID_DATE Invalid effective date
INVALID_EXPDATE Invalid expiry date
OTP_TIMED_OUT OTP has expired
PENDING_FOR_CARDVER Card information has not been verified
INELIGIBLE Card is not eligible to make payment
TRANSACTION_LIMIT_EXCEEDED Transaction value exceeds maximum limit set by bank
VALUE_EXCEEDED_LIMIT Transaction value exceeds maximum limit set by payment gateway
PENDING_FOR_PURCHASE OTP has been verified
TRANSACTION_BELOW_LIMIT Transaction value does not meet minimum limit set by bank
ORDERS_NOT_FOUND Order cannot be found
56
ORDERS_NOT_PAID Order cannot be processed
DUPLICATE_ORDERS Duplicate order
TRANSACTION_OUT_OF_LIMIT Transaction value is out of limit range set by bank
UNDETERMINED_BALANCE Undetermined balance in customer's account
INVALID_REQUEST Transaction failed
INVALID_TOKEN Invalid token
TOKEN_NOT_FOUND Token not found
INVALID_CARD Invalid card format

ERROR
CUSTOMER_CANCELLED Customer cancelled the payment
BLACKLISTED_BIN Transaction is rejected by risk management.
BLACKLISTED_IP Transaction is rejected by risk management.
BIN_VELOCITY Transaction is rejected by risk management.
IP_VELOCITY Transaction is rejected by risk management.
VALUE_EXCEEDED_LIMIT Transaction is rejected by risk management.
PENDING PENDING Transaction is pending
57
6 Appendix A: Napas Hosted Form Screenshots
6.1 Create Token transaction
58
6.2 Pay / Pay with returned Token transaction
59
7 Appendix B: Transaction flow
7.1 Pay with 3DSecure transaction flow
The following figure shows the flow of pay with 3DSecure transaction:
60

Napas Payment Gateway Techspec v3.0

Uploaded by

Document Information

Original Description:

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 Payment Gateway Techspec v3.0

Uploaded by

Copyright:

Available Formats

NATIONAL PAYMENT CORPORATION OF VIETNAM

Hanoi, Oct 2017

1.4 How to Use this Document

- Field Name: name of field as used in JSON form

- R: Required – field must be presented

A – Merchant sends request to get an access_token to Authorization Server.

2.2.2 Card Information

HTTP Method POST

Authentication This operation requires authentication via the following method:

inputParameters.clientI string R IP of the customer client

false: disable 3DSecure flow

result string R A system-generated high level overall result of the operation

orderReference="Thanh toan hoa don"

merchantId string Merchant identifier R R R

clientIP string Customer’s ip address RE RE RE

environment string Integration environment: RE RE RE

WebApp: desktop web

MobileApp: mobile web/mobile app

cardScheme string Card schemes in use: RE RE RE

CreditCard: international cards (Visa, Mastercard, Amex…)

AtmCard: domestic cards

enable3DSecure string Supports 3DSecure to authorize cardholder (always be false with RE RE RE

true: enables 3DSecure flow

false: disables 3DSecure flow

apiOperation string PAY: normal payment with card details. R R

PAY_WITH_RETURNED_TOKEN: pay and tokenize card details.

orderAmount string Order amount (display on form) R R

orderCurrency string Order currency (display on form) R R

orderReference string Order short description (display on form) R R

orderId String Order identifier (must be unique) R R R

channel string Merchant business code R R

sourceOfFundsType string Always be CARD R R

dataKey string Secured key for communication with Napas R R R

serviceCode string Reserved for future use O O

language string Napas Hosted Form display language O O O

*R: field must be presented

*O: field is optional

orderReference="Thanh toan hoa don"

merchantId string Merchant identifier R R R

clientIP string Customer’s ip address RE RE RE

environment string Integration environment: RE RE RE

WebApp: desktop web

MobileApp: mobile web/mobile app

cardScheme string Card schemes in use: RE RE RE

CreditCard: international cards (Visa, Mastercard, Amex…)

AtmCard: domestic cards

enable3DSecure string Supports 3DSecure to authorize cardholder (always be false with RE RE RE

true: enables 3DSecure flow

false: disables 3DSecure flow

apiOperation string PAY: normal payment with card details. R R

PAY_WITH_RETURNED_TOKEN: pay and tokenize card details.

orderAmount string Order amount (display on form) R R

orderCurrency string Order currency (display on form) R R

orderReference string Order short description (display on form) R R

orderId String Order identifier (must be unique) R R R

channel string Merchant business code R R

sourceOfFundsType string Always be CARD R R

dataKey string Secured key for communication with Napas R R R

serviceCode string Reserved for future use O O

language string Napas Hosted Form display language O O O

*R: field must be presented

*O: field is optional

The result will be included in napasResult parameter.