0% found this document useful (0 votes)

77 views

UMAPI .Net Integration Manual v2.8 PDF

Uploaded by

Uthara Ramanandan

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

77 views

UMAPI .Net Integration Manual v2.8 PDF

Uploaded by

Uthara Ramanandan

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 83

Unified Merchants API (UMAPI) .

Net
Integration Manual

Version 2.8

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual

Contents
1 INTRODUCTION........................................................................................................5
1.1 Purpose and Objective ....................................................................................5
1.2 Audience ...........................................................................................................5
1.3 Assumptions / Exclusions ..................................................................................5
1.4 Terminology / Conventions .............................................................................5
1.5 Contact Point ....................................................................................................6
1.6 Pre-requisites for UMAPI Integration ...............................................................6
2 TECHNICAL OVERVIEW...........................................................................................9
2.1 High-level Features and Functionality ...........................................................9
2.2 Transaction Flows ............................................................................................10
2.2.1 Credit Transaction using UMAPI Browser Submission ......................11
2.2.2 Credit Transaction using UMAPI Server Submission ........................14
2.2.3 UMAPI Debit Transaction Engine .......................................................18
2.3 URL Redirection (Success and Failure) ........................................................21
2.4 Message Format .............................................................................................21
2.4.1 Credit Payment Request (From Merchant to eNETS) .....................22
2.4.2 Credit Payment Notification (From eNETS to Merchant) ...............29
2.4.3 Credit Payment Acknowledgement (From Merchant to eNETS).31
2.4.4 Credit Payment Response (From eNETS to merchant) ..................32
2.4.5 Debit Payment Request (From Merchant to eNETS) ......................35
2.4.6 Debit Payment Notification (From eNETS to merchant) ................37
2.4.6 Debit Payment Acknowledgement (From Merchant to eNETS) ..39
2.4.7 Debit Payment Response (From eNETS to merchant)....................40
2.4.8 UMID Payment Request (From Merchant to eNETS) ......................42
2.4.9 Supplementary Message ....................................................................49
3 ARCHITECTURE.......................................................................................................50
3.1 Package Structure ..........................................................................................50
3.2 Main Components ..........................................................................................51
3.3 Functions ..........................................................................................................51
3.4 Supporting files ................................................................................................52
4 API INSTALLATION AND SETUP .............................................................................53

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual

4.1 Pre-requisites for deploying UMAPI ..............................................................53

4.2 Merchant UMAPI Package ...........................................................................53
4.3 Hosting of Domain Name / Internet Connectivity .....................................53
4.4 Server Setup .....................................................................................................53
4.5 Installation of UMAPI .......................................................................................54
4.6 Generation of Public/Private key pair .........................................................56
4.7 Encryption of Private key password .............................................................58
4.8 Configuration of eNETS Merchant Admin ...................................................58
4.8.1 Website URL ..........................................................................................59
4.8.2 Public Key..............................................................................................59
4.9 Configuration of proxy settings .....................................................................61
4.10 Configuration of UMAPI Config files ..........................................................62
4.10.1 Using Relative Path In UMAPI Config File .........................................62
4.11 NET UMAPI Strong Name Reference .........................................................63
4.11.1 Compile time reference .....................................................................63
4.11.2 Run time reference ..............................................................................63
5 DEVELOP SCRIPTS ..................................................................................................64
5.1 Review of UMAPI Sample scripts ...................................................................64
5.2 Customisation of scripts by merchant .........................................................64
6 USING UMAPI FOR RECURRING TRANSACTION ................................................64
6.1 Sample code ...................................................................................................64
7 USING UMAPI FOR IAP TRANSACTION ................................................................65
8 USING CREDIT PAYMENT REQUEST WITH SUPPLEMENTARY MESSAGE ............66
8.1 Sample code ...................................................................................................66
9 RESPONSE CODES .................................................................................................67
A.1 Credit Transaction Stages ............................................................................67
A.2 Credit Acquirer Response Codes ...............................................................67
A.3 Credit Response Codes ................................................................................68
A.4 Debit Transaction Stages ..............................................................................71
A.5 Debit Acquirer Response Codes .................................................................71
A.5.1 Successful Transaction ........................................................................71
A.5.2 Bank Related Response Codes .........................................................72

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual

A.5.3 Gateway Related Response Codes .................................................73

A.5.4 System / Application Related Response Codes .............................75
A.5.5 Merchant Related Response Codes ................................................76
APPENDIX B CHANGE HISTORY .................................................................................78

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual

1 Introduction
1.1 Purpose and Objective

The main purpose of the UMAPI Merchant Implementation guide is to provide merchants with
the necessary technical information when integrating their applications with eNETS II, using the
Unified Merchant API (UMAPI).

This manual contains a technical overview of the UMAPI, the payment transaction flows as well
as the message formats required between eNETS II and the merchant system. This manual also
contains step-by-step setup instructions and sample scripts or java programmes which
merchants will find useful in their integration efforts with eNETS II.

1.2 Audience

The UMAPI Merchant Implementation Guide is intended as a technical guide for merchant
developers and system integrators who are responsible for designing or programming the
necessary online applications to integrate with eNETS II.

1.3 Assumptions / Exclusions

Merchant developers and system integrators are expected to have working knowledge of the
Java 1.4 SDK platform, and Web / Application server technology. In addition, a basic
understanding of the purpose / types of digital certificates is also essential.

1.4 Terminology / Conventions

Term Description
Customer A buyer using the internet to make a payment
Merchant An entity that offer goods or services for sale on the internet
UMAPI Unified Merchant Application Programming Interface
URL Uniform Resource Locator. Specifies the "address" of a resource in the internet
DSA Secure Hash Algorithm
Keystore A special file that stores public and private keys used in Public Key Infrastructure
(PKI). A keystore file can be generated using a Java tool called "keytool"
Signing This certificate can be obtained from any Certificate Authority. It is used to
cert digitally sign a message
SSL Secure Socket Layer
OpenPGP Non-proprietary protocol for encrypting data using public key cryptography. The
OpenPGP protocol defines the standard formats for encrypted messages,
signatures and certificates for exchanging public keys
UMID Universal Merchant ID

5
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
1.5 Contact Point

Please feel free to address any comments or feedback that you may have on the UMAPI
Integration manual by:

Post: eNETS Pte Ltd

298 Tiong Bahru Road
#06-01/06 Central Plaza
Singapore 168730

Operating Hours: 8:30am to 5:30pm, Mondays - Fridays.

Closed on Saturdays, Sundays and Public Holidays.

Email: [email protected]
Hotline: (65) 6274 1212

1.6 Pre-requisites for UMAPI Integration

The UMAPI .Net can run on any system that satisfies the following requirements:

1. Hardware

The Merchant API can run on any operating system that supports Microsoft .NET Framework
1.1 and above.

2. Operating System

Merchant must have an operating system that supports Windows 2000 or above.

3. Browsers

The recommended browsers that customers should use when making payment with eNETS
over the internet is Microsoft Internet Explorer 5.0 and above; Mozilla Firefox 2.0 with
support for javascript and cookies.

4. IP Static Address* :

The IP address of the merchant’s server to server redirection URLs (for notification, POST or
Transaction End messages) should be static as eNETS does not support dynamic IPs.

eNETS will refresh the IP caching on a scheduled weekly basis to support merchant’s change
of IP address by 1 Apr 2016
 eNETS will not be able to refresh the system on emergency basis as the refresh exercise
will affect the whole gateway.

 For change of your IP address, merchant should inform eNETS at least 2 weeks in
advance before implementing any IP changes at merchants end. Upon receiving the
request from the merchant, eNETS will inform the merchant on the next scheduled
refresh date of eNETS system to register the new IP address of merchant.

 If the change of IP address is done on an adhoc basis (without informing eNETS),

merchants have to roll back the IP address change to restore the service.

6
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
5. Merchant SSL Certificates* (Applicable if the merchant uses HTTPS protocol)

Merchant should provide the following information to eNETS at least 3 weeks in advance
before implementing the changes at merchant’s end:

a) UAT Certificates
i) CA Root Certificates
ii) Intermediate Certificates /Chain Certificates (if any)

b) Production Certificates
i) CA Root Certificates
ii) Intermediate Certificates /Chain Certificates (if any)

Pre-production
 The CA Root/Intermediate UAT Certificates will be loaded onto the eNETS UAT
environment. Merchants are required to perform at least one round of testing to
ensure that end-to-end transaction flows are normal with the new certificates.

 The CA Root/Intermediate UAT and Production Certificates should be identical.

 Only upon successful completion of merchant’s testing in UAT environment, the

Production Root/Intermediate certificates will then be loaded onto the eNETS
Production environment.

 Both Production and Merchant’s UAT CA Root/Intermediate Certificates will be

verified by eNETS before loading onto the eNETS system.

 eNETS reserves the rights to reject loading the certificates without getting prior
approval from merchants if the CA Root Certificates are suspected or found to be
causing abnormalities to the eNETS system. In such scenarios. eNETS will inform the
merchant before or after removal, depending on the situation.

Post Production
 eNETS reserves the rights to remove the Merchant’s CA Root Certificates at any
point of time without getting prior approval if the CA Root Certificates are
suspected or found to be causing abnormalities to the eNETS system. In such
scenarios, eNETS will inform the merchant before or after removal, depending on
the situation.

All the points mentioned above are also applicable for the subsequent change or
renewal of Merchant’s SSL certificates after the integration.

* Points 6 & 7 are applicable for merchants who are using any of the eNETS features and
services listed below & its associated impact :
 eNETS Notifications feature
Services to consumers will be disrupted as merchants will not receive the Server to
Server notifications and responses.

 Credit Merchants using eNETS POST response (Server to Server response)

eNETS will not be able to send the Post responses (server to server response) for the final
transaction status.
However, Consumers and Merchants will receive the browser responses as long as
consumers do not close the browser and disable the pop-up blocker.
7
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
 Debit Merchants using eNETS Transaction End (Server to Server response)
eNETS will not be able to send the Transaction end responses (server to server response)
for the final transaction status.
However, Consumers and Merchants will receive the browser responses as long as
consumers do not close the browser and disable the pop-up blocker.

8
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

2 Technical Overview
This chapter contains the following sections:

 High-level Features and Functionality

 Transaction Flows
 URL Redirection (Success and Failure)
 Message Format

2.1 High-level Features and Functionality

Merchants are offered multiple online payment services from the eNETS Payment Gateway,
such as Credit Card Payment, and Direct Debit Payment. All these services can be accessed
through a single interface, the Unified Merchant Interface, which listens to https requests at
www.enets.sg/enets2/PaymentListener.do.

Depending on the merchant type, merchants can send transaction requests to eNETS in one of
the following ways:

1. Using the UMAPI

The UMAPI is a component that is deployed at the merchant’s storefront to pass

transactional details to eNETS. It exposes interfaces for the merchant storefront application
to call upon, helping to form/parse the various messages exchanged between the
merchant and eNETS.

UMAPI gives merchants the flexibility of implementing their payment modules using one of
these submission modes:

a. Browser Submission
The merchant supplies UMAPI with payment information, and gets a ready-to-send
message from UMAPI. They perform their own http post, usually through a customer’s
browser redirection to eNETS.

b. Server Submission
Merchant supplies UMAPI with payment information, and UMAPI will form the
message and establish a server-to-server connection to eNETS to send the message
and receive the payment response.

All information exchanged between the merchant storefront and the eNETS Payment gateway
is in XML format. Please refer to Section 2.4 Message Format for more details.

The link from the merchant to eNETS is secured through the use of the OpenPGP protocol. The
data is encrypted using eNETS Gateway public key, and merchants have to digitally sign the
messages with their private certificate for non-repudiation.

9
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.2 Transaction Flows

 ]
 Credit Transaction using UMAPI Browser Submission
 Credit Transaction using UMAPI Server Submission
 UMAPI Debit Transaction Engine

10
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.2.1 Credit Transaction using UMAPI Browser Submission

If a customer uses the internet to make payment using the Credit Card gateway and the merchant uses the Browser Submission mode, the
flow described below will apply.

Note: In browser submission mode, the 3D Secure processes happen "transparently" between eNETS II and the customer’s browser.

Merchant
Server

Internet
1
Internet/Leased Line

10b 11
NETS
2
3
10a 4

5
6
7 eNets

Customer
8
9

Figure 1. Transaction Flow for eNETS Credit Transaction (Browser Submission)

11 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
No. Customer Merchant eNETS Credit
1 The customer browses to the merchant’s
web site and makes a purchase and
chooses to pay using eNETS Credit.

2 The Merchant Server uses the UMAPI to form

the Payment Request, and redirects the
customer to eNETS via customer’s browser.
Note: The merchant may pass the success,
failure and cancel URL in the Payment
Request message. If passed, these will be
used. Otherwise the success, failure and
cancel URL in the eNETS Credit merchant
profile will be used.
3 eNETS decrypts the Payment Request message
and verifies the merchant signature.
4  eNETS verifies the parameters in the
Payment Request and redirects the
customer to the Merchant Collection in
the following cases:
o Merchant did not specify the
Payment Mode.
o Merchant did not send the
Transaction amount.
o If the merchant profile indicates
that the merchant wants to
publish his merchant collection
page to gather additional
information from the customer.
Else the flow continues with step 7
5 Customer fills in the required information
at the merchant collection page and
clicks on submit to proceed with
payment.

12 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
No. Customer Merchant eNETS Credit
6 eNETS stores the gathered information in
database.
7 If the request does not contain the credit card
details of the customer, eNETS will re-direct the
customer to the Credit Payment Page.
Else the flow continues with step 9.
8 The customer enters the eNETS userID and Re-direct via consumer’s browser
password. They may login or enter their
credit card information if they do not
have an eNETS user ID and password.
Customer can choose to cancel at this
point.
Refer to step 12 for cancellation flow.
9 eNETS Credit processes the transaction.

10a eNETS will send the payment response to the

Merchant’s Notification URL provided by the
merchant to eNETS.
(This is transparent to customer.)
10b Merchant’s Notification URL receives the
payment response, processes the message
and returns a Notification
Acknowledgement message to eNETS
11a eNETS Credit sends the successful message to
customer in a new pop-up window and
redirects customer to merchant URL.
11b The merchant receives the Payment Re-direct via consumer’s
Successful message. browser

Exception / Reversal Scenarios

12 If customer chooses to cancel the transaction at Step 8, he will be redirected by eNETS Credit to the merchant’s cancel URL. There is no
post or notify message sent to the merchant for cancelling of transaction.

13 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
2.2.2 Credit Transaction using UMAPI Server Submission

 Non 3D Flow
 3D Flow

2.2.2.1 Non 3D Flow

If a customer uses the internet to make payment using the Credit Card gateway and the merchant uses the Server Submission mode, the flow
described below will apply:

Merchant
Server

Internet
1
Internet/Leased Line

1
3 2

5
NETS

eNets

Customer

Figure 2. Transaction Flow for Credit Transaction (Server Submission – Non 3D Flow)

14 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
No. Customer Merchant eNETS Credit
1 The customer browses the merchant’s
web site and makes a purchase and
chooses to pay using eNETS Credit.
2 The Merchant Server uses UMAPI to form the
Payment Request and send the request
through a direct server-to-server connection
to eNETS.
3 eNETS decrypts the Payment Request message
and verifies the merchant signature. eNETS
Credit processes the transaction and returns the
Payment Response message.

4 UMAPI decrypts the Payment Response,

and verifies the eNETS signature. Based on
the Payment response returned, the
merchant updates its database and
inventory information, and displays a
receipt page to the customer.

15 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
2.2.2.2 3D Flow

1.1.Consumer
Customer sends
sendsPayment
Payment
Request
RequesttotoMerchant
Merchant

4. Merchant gets 3D Parameters and Merchant Server (UMAPI)

4. Merchant gets 3D Parameters
redirects customer to ACS and
redirects consumer to ACS

Internet

` 2. UMAPI passes
Internet 3. eNETS2 returns 3D Parameters information to eNETS2
7. eNET2 sends txn status to
Customer to UMAPI
Consumer Merchant via UMAPI

5. Customer redirects to
ACS for authentication eNETS2
5. Consumer redirects to
ACS for authentication

6. ACS Updates eNETS2

8. Redirect Customer to Merchant Page

ACS

Figure 3. Transaction Flow for Credit Transaction (Server Submission – 3D Flow)

16 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
No. Customer Merchant eNETS ACS
1 The customer shops at the
merchant site and submits
payment details to the
merchant for processing.

2 The merchant formulates payment

details with UMAPI for submission to
eNETS.
3 eNETS returns the 3D Parameters to
UMAPI (see section 2.4.4 Credit Payment
Response (From eNETS to merchant)
items 12 to 16). The 3D parameters are
only returned if NETSTXNSTATUS = 5 and
also normal non-3D flow will be
applicable if NETSTXNSTATUS is not equal
to 5.
4 The merchant processes the 3D
Parameters and redirects the customer
to the ACS server for authentication.
The ACS’ URL is contained in the field
named "acsUrl" (item 15 in section 2.4.4
Credit Payment Response (From eNETS
to merchant)). The merchant must
generate a form that contains the
variables "PaReq", "TermUrl" and "MD",
and post them to the "acsURL". These
values ("PaReq", "TermUrl" and "MD")
are to be obtained from the fields
named "PAreq", "termUrl", and "md" of
section 2.4.4 Credit Payment Response
(From eNETS to merchant).

5 Customer is redirected to ACS authenticates

ACS Server. Customer.

17 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
No. Customer Merchant eNETS ACS
6 ACS updates eNETS on the
authentication process.

7 eNETS processes the transaction with

the acquiring bank.

7a The merchant receives the eNETS notifies the merchant of the

transaction status. transaction result.

8 Merchant informs the eNETS redirects customer to the

customer accordingly of the merchant success or failure URL.
txn status through the
success, failure URL.

2.2.3 UMAPI Debit Transaction Engine

The UMAPI for Debit System is an internet-based direct-debit payment system that allows users to make payment over the World Wide Web. The
Merchant server is most likely a Web Server machine that communicates with the UMAPI Servers which in turn communicates with the Bank.

 The UMAPI Debit Transaction Data Flow

 The UMAPI Debit Transaction Web Flow

18 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
2.2.3.1 The UMAPI Debit Transaction Data Flow

Figure 4. Debit Engine Dataflow Diagram

19 eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
2.2.3.2 The UMAPI Debit Transaction Web Flow

The web flow (and the message flow) of this application is shown in the following diagram.
Each of the steps is thereafter described in greater detail.
Merchant Web Internet Payment
Bank Server
Server Gateway

1. Merchant Services
Consumer selects to pay by
Direct Debit, starting the
transaction process

2. Merchant Payment Request

Merchant ID, $ Amt, Merchant Reference
Code, Merchant signature
Stage 000005

3. User selects the Bank that

he has the Internet Banking
Account with.

4. IPG Payment request

Full Merchant payment request, Bank ID,
IPG Transaction Code, IPG signature
Stage 000001

5. User enters UID and

Password

6a. Notification
Bank Reference Code, IPG Transaction Code,
6b. Notification Bank ID, Bank signature
Full Bank Notification Message, Stage 000002
Merchant Reference Code, IPG signature
Stage 000006

7a. Acknowledge
Merchant Reference Code, Status,
Merchant signature
Stage 000007
7b. Acknowledge
Full Merchant Acknowledge message,
IPG Transaction Code, IPG signature
Stage 000003

8. Bank serves out result

page to user.

9a. Transaction End

(Server-to-Server)
9b. Transaction End Bank sends the first Txn End message
(Server-to-Server) (Server-to-Server) to the Gateway
After updating the Gateway database Stage 000004
the Txn End message is send to the
Merchant
Stage 000008

9c. Transaction End

(Popup Browser)
Bank Open new browser window
and redirects to the IPG with
Figure 5. UMAPI Debit Transaction Web Flow Status, IPG Transaction Code,
Bank ID, Bank signature
9d. Transaction End Stage 000004
(Popup Browser)
Full Bank Txn End message,
Merchant Reference Code, IPG signature
Stage 000008

Note: i) Merchant’s notification URL (6b) to receive full bank notification message on step 6b.
ii) Merchant’sTxnEnd2 (9b) URL to receive updated transaction status. [server-to-server]
iii) Merchant’s TxnEnd (9d) URL to receive bank TxnEnd message.

20
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.3 URL Redirection (Success and Failure)

Merchants need to develop their own success and failure pages and update the URLs to the
eNETS Administration and Report Portal or in credit transactions only, specify URLs during
payment request to eNETS.

Upon the completion of a transaction, the browser will automatically redirect to the merchant’s
success or failure page according to the transaction status. For detailed information, refer to
section 2.4 Message Format.

2.4 Message Format

All messages exchanged between the merchant and eNETS are XML messages. They are
signed and encrypted using openPGP, then posted to the eNETS II payment gateway as a
parameter ‘message’. Message formats are specified in XML schema. Refer to Appendix A for
message schema and examples.

In the tables that follow, the Payment Mode and Inclusion columns include the values in the
following table:

Field Meaning
Payment Mode Indicates which payment mode the field is applicable.
C – Common to all payment modes
CC – Credit Card Payment
DD – Direct Debit Payment
Inclusion R – Required
C – Conditional
O – Optional
N – Not applicable

Message Formats:

Credit:
 Credit Payment Request (From Merchant to eNETS)
 Credit Payment Notification (From eNETS to Merchant)
 Credit Payment Acknowledgement (From Merchant to eNETS)
 Credit Payment Response (From eNETS to merchant)
Debit:
 Debit Payment Request (From Merchant to eNETS)
 Debit Payment Notification (From eNETS to merchant)
 Debit Payment Acknowledgement (From Merchant to eNETS)
 Debit Payment Response (From eNETS to merchant)
UMID:
 UMID Payment Request (From Merchant to eNETS)

21
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.1 Credit Payment Request (From Merchant to eNETS)

The Payment Request message is sent by the merchant to eNETS to initiate internet credit card
payment transactions.

Note: For Credit Card Authorisation transactions, there is a need to perform capture of the
transactions to complete the transaction. Authorisation reserves the credit limit for a
particular credit card while capture deducts the actual amount from the credit card.
Authorised transactions that are not captured are automatically released after a period
of time depending on the issuing bank. (The issuing bank of the credit card decides the
period.) Partial capture is allowed. (e.g. Authorisation amount is $800 but only captured
$600.) Only a single capture is allowed for a single authorisation. (e.g. when authorisation
amount is $800, if $600 had been captured, another capture of $200 is not allowed.)
Capture Reversal is not allowed in eNETS gateway.

Optional supplementary message may be submitted together with the Credit Payment Request
to eNETS for additional processing. Refer to section 2.4.9 (Supplementary Message) for details.

S/N Field Name Remark Max Paymen Inclusion

For Direct Debit Payment

B – Browser Submission
5 TxnAmount Transaction amount in cents 10 C R R
for all currencies. E.g. for
$10.00 in SGD, the TXN_AMT
will be equal to 1000. For
¥10,000 in JPY, the TXN_AMT
will be equal to 1000000.
22
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
6 CurrencyCode Identifies the type of 3 C O R
currency used. Three-
character currency code
following the ISO 4217
standard.
If not set, defaults to SGD.
7 MerchantTxnRef Unique reference code 20 C R R
assigned by the merchant
for this transaction.

For Credit Transactions: -

For SALE and AUTH
transactions, it must be a
unique Merchant Reference
as specified by the
merchant storefront, or any
ID that is used by the
merchant to identify the
transaction.

eNETS will reject duplicate

MERCH_REF. This is to
prevent multiple submissions.

For CAPTURE transactions, it

must contain the same
Merchant Reference
corresponding to the prior
AUTH transaction.

For CREDIT transactions, it

must contain the same
Merchant Reference
corresponding to the prior
SALE or CAPTURE
transaction.
8 MerchantTxnDt Format: yyyyMMdd 21 C O O
m HH:mm:ss.SSS
Transaction date as
recorded by merchant
server.

9 MerchantCertId ID of the OpenPGP 5 C R R

Certificate used for this
transaction. It is assigned by
eNETS after merchant
generates his key pair and
uploads the public
certificate to the gateway.

23
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
10 PaymentType Payment mode of credit 5 CC R R
card txn
AUTH – Authorisation
CAPT – Capture
AUTH and CAPT is where the money
is first reserved from the
cardholder’s credit account upon
successful Authorisation. The money
is only deducted when the
Merchant captures the Auth
transaction. If the Auth transaction
is not captured within a stipulated
time (determined by bank), the
reserved credit will be restored.
SALE – Sale
This is where the money is deducted
from the cardholder’s credit
account immediately.
CRED – Credit
Is where the deducted money will
be refunded back to the
cardholder's credit account?
RAUTH – Reverse
Authorisation
RSALE – Reverse Sale
RCREDIT – Reverse Credit
11 Pan Credit Card Number 19 CC O R

For Server submission, this

field is mandatory for SALE
and AUTH transactions only.
12 Cvv Credit Card Validation 4 CC O O
Value
13 ExpiryDate Credit Card Expiry Date 4 CC O R
(YYMM)
14 CardHolderNa Name of Cardholder 255 CC O O
me
15 SuccessUrl eNETS will redirect to the 80 C O N
merchant Success URL upon
successful purchase

* Only applicable for

browser submission, optional.
If not sent in the request,
SuccessUrl that was stored in
the Merchant Profile during
registration will be used.

24
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
16 SuccessUrlPara Query String to be 255 C O N
ms appended to the Merchant
Success URL, which displays
the success page to
shopper.

E.g.
session_id=1111&member_id
=23
17 FailureUrl eNETS will redirect to this 80 C O N
page when errors are
encountered during
payment.

*Only applicable for browser

submission, optional. If not
sent in the request, FailureUrl
that was stored in the
Merchant Profile during
registration will be used.
18 FailureUrlparam Query String to be 255 C O N
s appended to the Merchant
Failure URL, which displays
error diagnostics information
to shopper.

19 NotifyUrl eNETS will send the Notify 80 C O N

Message to this URL

*Only applicable for browser

submission, optional. If not
sent in the request, NotifyUrl
that was stored in the
Merchant Profile during
registration will be used.

20 NotifyUrlParams Query String to be 255 C O N

appended to the Merchant
Notify URL.

21 PostUrl eNETS will post the 80 CC O O

transaction information to
the Merchant POST URL for
logging and inventory
update. This URL is not visible
to the shopper.

22 PostUrlParams Query String to be 255 CC O O

appended to the Merchant
Post URL.

25
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
23 CancelUrl URL to redirect to when 80 CC O O
shopper clicks cancel during
the payment process.

24 CancelUrlPara Query String to be 255 CC O O

ms appended to the Merchant
Cancel URL.
25 Stan Credit Note Number (must 6 CC O O
be unique for the same
batch)

# Mandatory for CAPTURE

and CREDIT transactions
only.

Fields 26 – 29 are applicable for 3D Secure transactions. Merchants who connect to a third-
party MPI for credit card number authentication may send the authentication results to
eNETS.

26 Cavv Cardholder authentication 28 CC C C

Verification Value.
Required when the value of
Transaction Status is "Y" or
"A".
27 purchaseXid Transaction Identifier 20 CC C C

26
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
28 Status Indicates whether a 1 CC R R
transaction qualifies as an
authenticated transaction.

Y = Authentication
Successful.
Customer was successfully
authenticated. All data
needed for clearing,
including the Cardholder
Authentication Verification
Value, is included in the
message.

N = Authentication Failed.
Customer failed
authentication. Transaction
denied.

U = Authentication Could
Not Be Performed.
Authentication could not be
completed, due to
technical or other problems.

A = Attempts Processing
Performed.
Authentication could not be
completed, but a proof of
authentication attempt
(CAVV) was generated.
29 ECI Electronic Commerce 2 CC C C
Indicator
30 Param1 Reserved 100 CC N O
Valid values:
- "RPP" (Using UMAPI for RPP
Transaction)
- "IAP" (see section 8 Using
UMAPI for IAP Transaction)

Note:
- Strings in uppercase
- "RPP" for specific
merchants only
- "IAP" for merchants
subscribed to
International Airline
Program.

27
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
31 Param2 Reserved (for RPP 550 CC N O

for IAP, see section 8 Using

UMAPI for IAP Transaction)

Param3 Reserved 100 CC N O

32
Param4 Reserved 100 CC N O
33
Param5 Reserved 100 CC N O
34
ClientType Indicates what kind of 1 C O N
35
device the customer used
for the transaction.
W – From computer
browsers
M – From mobile device or
tablet
browsers/applications.

If not set, defaults to W.

Based on this, eNETS will

redirect customer to the
web (current) pages or
mobile pages accordingly.

28
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.2 Credit Payment Notification (From eNETS to Merchant)

S/N Field Name Remark Max Paymen Inclusion

Length t Mode Credit Credit
Browser Server
1 NetsMid Merchant ID. Uniquely 20 C R R
identifies merchant. Value
assigned by eNETS.
2 Tid Terminal ID. Identifies the 20 C O O
merchant terminal, if
applicable, from where
transaction originates.
If not present in the request,
eNETS will set the Terminal ID
to the IP address from where
the request originates.
3 PaymentMode Payment method of the 2 C C R
transaction
CC – Credit Card
This field is required if the
merchant does not publish his
collection page.
If not sent in the request,
eNETS will redirect the
customer to the Merchant
Collection Page to select the
payment mode.
4 SubmissionMode S – Server Submission 1 C R R
B – Browser Submission
For Direct Debit payment, set
to B.
5 TxnAmount Transaction amount in cents 10 C R R
for all currencies. E.g. for
$10.00 in SGD, the TXN_AMT
will be equal to 1000. For
¥10,000 in JPY, the TXN_AMT
will be equal to 1000000.
6 CurrencyCode Identifies the type of currency 3 C O R
used. Three-character
currency code following the
ISO 4217 standard.
If not set, defaults to SGD.

29
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
7 MerchantTxnRef Unique reference code 20 C R R
assigned by merchant for this
transaction.

For Credit Transactions: -

For SALE and AUTH
transactions, it must be a
unique Merchant Reference
as specified by the merchant
storefront, or any ID that is
used by the merchant to
identify the transaction.

eNETS will reject duplicate

MERCH_REF. This is to prevent
multiple submissions.

For CAPTURE transactions, it

must contain the same
Merchant Reference
corresponding to the prior
AUTH transaction.

For CREDIT transactions, it

must contain the same
Merchant Reference
corresponding to the prior
SALE or CAPTURE transaction.
8 MerchantTxnDt Format: yyyyMMdd 21 C O O
m HH:mm:ss.SSS
Transaction date as recorded
by merchant server.

9 MerchantCertId ID of the OpenPGP 5 C R R

Certificate used for this
transaction. It is assigned by
eNETS after merchant
generates his key pair and
uploads the public certificate
to the gateway.
10 netsTxnRef Unique reference code 17 C R 3
assigned by eNETS this
transaction
11 netsTxnDtm Transaction date time as 21 C R 4
recorded by eNETS
12 netsTxnStatus Status of the Transaction. 5 C R 6
0000: Transaction Successful
05: Do not honour (2
characters mean transactions
rejected at bank end)
-3093: Failed transaction
within eNETS system.
30
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.3 Credit Payment Acknowledgement (From Merchant to eNETS)

S/N Field Name Remark Max Payment Inclusion

Length Mode Credit Credit
Browser Server
1 NetsMid Merchant ID. Uniquely 20 C R R
identifies merchant. Value
assigned by eNETS.
2 MerchantTxnRef Unique reference code 20 C R 2
assigned by merchant for this
transaction.
3 MerchantTxnStat Status of the Transaction: 4 C R 2
us 0000: Transaction Successful

4 MerchantCertId ID of the OpenPGP 5 C R R

Certificate used for this
transaction. It is assigned by
eNETS after merchant
generates his key pair and
uploads the public certificate
to the gateway.
5 NetsTxnRef Unique reference code 17 C R 3
assigned by eNETS for this
transaction.

Note: MerchantTxnStatus of 0000 or any other value means the merchant accepted the result
of the transaction.

31
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.4 Credit Payment Response (From eNETS to merchant)

eNETS redirects the customer to the merchant’s success or failure URL depending on the
transaction status. As part of this redirection, the Payment Response message will be posted.

In a server-to-server credit card transaction, the Payment Response is returned in the server
response.

S/N Field Name Remark Max Payment Inclusion

Length Mode
Credit Credit
Browser Server
1 NetsMid Merchant ID. Uniquely identifies 20 C R R
merchant. Value assigned by
eNETS.
2 merchantTxnRef Unique reference code assigned 20 C R R
by merchant for this transaction.
3 netsTxnRef Unique reference code assigned 17 C R R
by eNETS for this transaction.
4 netsTxnDtm Transaction date and time as 21 C R R
recorded by eNETS.
5 paymentMode Payment method of the 2 C R R
transaction
CC – Credit Card.
6 netsTxnStatus Status of the Transaction. 1 C R R
 0: Success
 1: Failure
 2: Resubmission of the
successful transaction3:
Resubmission of the
unsuccessful transaction
 5: Both merchant and card
are 3D enrolled. For server-to-
server flow, redirect customer
browser to acsURL.
 9: Cancel
7 netsTxnRespCode Response Code returned by 5 C R R
individual successful payment, or
error codes. Refer to Section 5 for
the list of Response Codes.

00: Success [Approved – 2

characters response code
means the response is from
bank]
-1230: Transaction has been
cancelled. (Transaction
terminated at eNETS for negative
sign response code)
8 netsTxnMsg Transaction Message. E.g.: 255 C R N
Approval for success transaction.
9 customAttribute Only for merchants that publish - C O O
their collection page. This field
returns the data collected from
the customer.
10 bankAuthId Bank Authorisation code. For 6 CC C1 C2
Credit Card transactions only.
May be empty for failure cases.

1,2 Present only when transaction is successful.

32
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Payment Inclusion
Length Mode
11 netsAmountDeduc Amount Deducted in cents. 10 CC C3 C4
ted

3,4 Present when transaction is successful, otherwise optional.

33
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Payment Inclusion
Length Mode
Credit Credit
Browser Server
12 Pareq PAreq value which is forwarded - CC R R
to the Access Control Server as
part of the customer redirection.
13 TermUrl termurl value (contains eNETS url 20 CC R R
which the customer gets
redirected to by the Access
Control Server after 3D
authentication).
14 md md value which is used by the 20 CC R R
MPI to track / reference a
particular transaction.
15 acsUrl acsurl field value (contains 20 CC R R
customer’s Access Control Server
url).
16 errorCode errorcode value thrown by the 20 CC R R
MPI
(If any) which will be forwarded
to the Access Control Server.

Note: The values for S/N 12 – 16 are returned to and to be passed by the merchant if the credit
card is 3D secure enrolled.

34
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.5 Debit Payment Request (From Merchant to eNETS)

S/N Field Name Remark Max

Length
1 NetsMid Merchant ID. Uniquely identifies merchant. Value assigned 20
by eNETS.
2 Tid Terminal ID. Identifies the merchant terminal, if applicable, 20
from where transaction originates.
If not present in the request, eNETS will set the Terminal ID to
the IP address from where the request originates.
3 TxnAmount Transaction amount in cents for all currencies. E.g. for $10.00 10
in SGD, the TXN_AMT will be equal to 1000. For ¥10,000 in
JPY, the TXN_AMT will be equal to 1000000.
4 CurrencyCod Identifies the type of currency used. Three-character 3
e currency code following the ISO 4217 standard.
If not set, defaults to SGD.
5 MerchantTxnR Unique reference code assigned by merchant for this 20
ef transaction.
6 MerchantCert ID of the Certificate used for this transaction. It is assigned by 5
Id eNETS after merchant generates his key pair and uploads
the public certificate to the gateway.
7 MerchantTim A time zone is a region of the Earth that has adopted the 6
eZone same standard time, usually referred to as the local time.
MerchantTimeZone means the time zone in which the
Merchant is located (e.g. "+11:30").
8 merchant_txn Transaction Date (dd/mm/yyyy format) 10
_date
9 merchant_txn Transaction Time (hh:mm:ss format) 8
_time
10 PaymentMod Payment method of the transaction 2
e DD – Direct Debit
This field is required if the merchant does not publish his
collection page.
If not sent in the request, eNETS will redirect the customer to
the Merchant Collection Page to select the payment mode.
11 SubmissionMo B – Browser Submission 1
de For Direct Debit payment, set to B.
12 ClientType Indicates what kind of device the customer used for the 1
transaction.
W – From computer browsers
M – From mobile device or tablet browsers/applications.

If not set, defaults to W.

Based on this, eNETS will redirect customer to the web

(current) pages or mobile pages accordingly.
13 Param1 Reserved Defined
by user
14 Param2 Reserved Defined
by user
15 Param3 Reserved Defined
by user
16 Param4 Reserved Defined
by user
17 Param5 Reserved 35 Defined

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
by user

36
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.6 Debit Payment Notification (From eNETS to merchant)

S/N Field Name Remark Max Payment Inclusion

Length Mode
1 NetsMid Merchant ID. Uniquely identifies 20 C R
merchant. Value assigned by eNETS.
2 Tid Terminal ID. Identifies the merchant 20 C R
terminal, if applicable, from where
transaction originates.
If not present in the request, eNETS
will set the Terminal ID to the IP
address from where the request
originates.
3 TxnAmount Transaction amount in cents for all 10 C R
currencies. E.g. for $10.00 in SGD, the
TXN_AMT will be equal to 1000. For
¥10,000 in JPY, the TXN_AMT will be
equal to 1000000.
4 CurrencyCode Identifies the type of currency used. 3 C R
Three-character currency code
following the ISO 4217 standard.
If not set, defaults to SGD.
5 Dest_Exchg_Rate The exchange rate to convert the 12 C R
Txn Amount to Txn Base Amount.
6 MerchantTxnRef Unique reference code assigned by 20 C R
merchant for this transaction.

7 MerchantCertId ID of the Certificate used for this 5 C R

transaction. It is assigned by eNETS
after merchant generates his key
pair and uploads the public
certificate to the gateway.
8 NetsTxnRef Unique reference code assigned by 17 C R
eNETS for this transaction.
9 Gw_Txn_Date Date on which transaction will be 10 C R
valued by Gateway.
10 GW_Txn_Time Time of transaction as recorded by 8 C R
Gateway.
11 GW_Time_Zone Time Zone (relative to GMT) of the 6 C R
transaction date.
12 netsTxnStatus Status of the Transaction. 1 C R
 0: Success
 1: Failure

Note: For NetsMid created after 11th

April 2011, this field contains an
intermediate transaction status and
SHALL NOT be used by merchants
for processing. The final transaction
status is obtainable from the
‘netsTxnStatus’ field in section 2.3.8
Debit Payment Response (From
eNETS to merchant).

37
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Payment Inclusion
Length Mode
13 GW_Value_date Date on which transaction will be 10 C R
valued by Gateway.
Format is DD/MM/YYYY
14 Bank_ID Uniquely identifies each Bank. 4 C R
15 Bank_Ref_Code BANK reference code for this 20 C R
Transaction.
16 Bank_Status Status of the transaction. 5 C R
17 Bank_Time_Zone Time Zone (relative to GMT) of the 6 C R
transaction.
18 Bank_Txn_Date Date on which total amount is 10 C R
debited
from the Customer account.
Format: DD/MM/YYYY
19 Bank_Txn_Time Time at which total amount is 8 C R
debited from the Customer
account.
20 Bank_Remarks Free form text by BANK to be used 30 C R
for display or logging purpose.

Informational field and not for

processing purposes.
21 Retry The number of retries for current 4 C R
MerchantTxnRef.
22 Version Software Version 10 C O
23 Param1 Reserved - C O
24 Param2 Reserved - C O
25 Param3 Reserved - C O
26 Param4 Reserved - C O
27 Param5 Reserved - C O
28 Param11 Reserved - C O
29 Param12 Reserved - C O
30 Param13 Reserved - C O
31 Param14 Reserved - C O
32 Param15 Reserved - C O

Note : Merchant may choose to read only the necessary parameters to reference back to the
transaction.

38
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.6 Debit Payment Acknowledgement (From Merchant to eNETS)

S/N Field Name Remark Max

Length
1 NetsMid Merchant ID. Uniquely identifies merchant. Value assigned 20
by eNETS.
2 MerchantTxnR Unique reference code assigned by merchant for this 20
ef transaction.
3 MerchantTxnS Status of the Transaction: 5
tatus 00000: success
4 MerchantCert ID of the OpenPGP Certificate used for this transaction. It is 5
Id assigned by eNETS after merchant generates his key pair
and uploads the public certificate to the gateway.
5 netsTxnRef Unique reference code assigned by eNETS this transaction 17
6 Param1 Reserved Defined
by user
7 Param2 Reserved Defined
by user
8 Param3 Reserved Defined
by user
9 Param4 Reserved Defined
by user
10 Param5 Reserved Defined
by user
11 Retry The number of retries for current MerchantTxnRef. 4
12 Version Software Version 10

39
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.7 Debit Payment Response (From eNETS to merchant)

S/N Field Name Remark Max

Length
1 netsMid Merchant ID. Uniquely identifies merchant. Value assigned 20
by eNETS.
2 merchantTxnR Unique reference code assigned by merchant for this 20
ef transaction.
3 netsTxnRef Unique reference code assigned by eNETS for this 17
transaction
4 Tid Terminal ID. Identifies the merchant terminal, if applicable, 20
from where transaction originates.
If not present in the request, eNETS will set the Terminal ID to
the IP address from where the request originates.
5 netsTxnStatus Status of the Transaction. 1
 0: Success
 1: Failure
 9: Cancel

Note: This field contains the final transaction status and

SHALL BE used by the merchants for processing.
6 netsTxnRespCo Response Code returned by individual payment instruments, 13
de or error codes. Refer to Section 6.1 for the list of Response
Codes.

This is composed of 2 codes separated by "_0", the first part is

Transaction Stage Code and the second part is the Debit
Acquirers Response Code.
E.g.: 000008_000000 (successful transaction)
7 netsTxnMsg Transaction Message. (Refer to section 6.1) 255

This parameter is not applicable during transaction end

server to server message.

Informational field and not for processing purposes.

8 BANK_ID Assigned Bank Code 4
9 BANK_Ref_Cod Bank Reference Code for transaction. 20
e
10 BANK_Remarks Remarks from bank. 30

Informational field and not for processing purposes.

11 BANK_Txn_Dat Date on which transaction amount is debited. Format: 10
e dd/mm/yyyy

12 BANK_Txn_Tim Time at which transaction amount is debited. Format: 8

e hh:mm:ss

13 BANK_Time_Zo Time Zone (relative to GMT) of the transaction. 6

ne
14 BANK_Status Bank status of transaction. 5

15 GW_Txn_Date Date on which transaction will be valued by Gateway. 10

Format: dd/mm/yyyy

40
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max
Length
16 GW_Txn_Time Time of transaction as recorded by Gateway. Format: 8
hh:mm:ss

17 GW_Time_Zon Time Zone (relative to GMT) of the transaction date. 6

e
18 GW_Value_da Date on which transaction will be valued by Gateway. 10
te Format is DD/MM/YYYY
19 TxnAmount Transaction amount (destination amount) 10
20 Dest_Exchg_Ra Destination exchange rate 12
te
21 Dest_Curr_Cod Destination currency code 3
e
22 Src_Txn_Amt Transaction amount from source 10
23 Src_Exchg_Rat Source exchange rate 12
e
24 Src_Curr_Code Source currency code 3
25 Retry The number of retries for current MerchantTxnRef. 4
26 version Software version 10
27 Param1 Reserved -
28 Param2 Reserved -
29 Param3 Reserved -
30 Param4 Reserved -
31 Param5 Reserved -
32 Param11 Reserved -
33 Param12 Reserved -
34 Param13 Reserved -
35 Param14 Reserved -
36 Param15 Reserved -

Note : Merchant may choose to read only the necessary parameters to reference back to the
transaction.

41
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.8 UMID Payment Request (From Merchant to eNETS)

The UMID Payment Request should contain both Credit Payment Request and Debit Payment
Request.

Note: For UMID transaction, the customer can opt for Credit or Debit service
for payment. Thus it is required for merchant to send credit & debit
payment requests in order to process UMID transaction.

Credit Payment Request

S/N Field Name Remark Max Paymen Inclusion

Length t Mode Credit Credit
Browser Server
1 NetsMid UMID (Universal Merchant 20 C R R
ID). Uniquely identifies
merchant. Value assigned
by eNETS.
2 Tid Terminal ID. Identifies the 20 C O O
merchant terminal, if
applicable, from where
transaction originates.
If not present in the request,
eNETS will set the Terminal ID
to the IP address from where
the request originates.
3 PaymentMode Payment method of the 2 C C R
transaction
This field can be set to
"Empty"
since the payment mode is
not determined during the
payment request.
4 SubmissionMod For UMID Payment 1 C R R
e S – Server Submission
B – Browser Submission

5 TxnAmount Transaction amount in cents 10 C R R

for all currencies. E.g. for
$10.00 in SGD, the TXN_AMT
will be equal to 1000. For
¥10,000 in JPY, the TXN_AMT
will be equal to 1000000.
6 CurrencyCode Identifies the type of 3 C O R
currency used. Three-
character currency code
following the ISO 4217
standard.
If not set, defaults to SGD.

42
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
7 MerchantTxnRe Unique reference code 20 C R R
f assigned by the merchant
for this transaction.

For UMID Transactions: -

For SALE transactions, it must
be a unique Merchant
Reference as specified by
the merchant storefront, or
any ID that is used by the
merchant to identify the
transaction.

eNETS will reject duplicate

MERCH_REF. This is to prevent
multiple submissions.
8 MerchantTxnDt Format: yyyyMMdd 21 C O O
m HH:mm:ss.SSS
Transaction date as
recorded by merchant
server.

9 MerchantCertId ID of the OpenPGP 5 C R R

Certificate used for this
transaction. It is assigned by
eNETS after merchant
generates his key pair and
uploads the public
certificate to the gateway.
10 PaymentType Payment mode of UMID txn 5 CC R R
SALE – Sale
This is where the money is
deducted from the
cardholder’s credit account
immediately.

Note: Sale is only supported

for UMID.
11 Pan Credit Card Number 19 CC O R

For Server submission, this

field is mandatory for SALE
and AUTH transactions only.
12 Cvv Credit Card Validation Value 4 CC O O
13 ExpiryDate Credit Card Expiry Date 4 CC O R
(YYMM)
14 CardHolderNa Name of Cardholder 255 CC O O
me

43
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
15 SuccessUrl eNETS will redirect to the 80 C O N
merchant Success URL upon
successful purchase

* Only applicable for browser

submission, optional. If not
sent in the request,
SuccessUrl that was stored in
the Merchant Profile during
registration will be used.

16 SuccessUrlPara Query String to be 255 C O N

ms appended to the Merchant
Success URL, which displays
the success page to
shopper.

E.g.
session_id=1111&member_id
=23
17 FailureUrl eNETS will redirect to this 80 C O N
page when errors are
encountered during
payment.

*Only applicable for browser

19 NotifyUrl eNETS will send the Notify 80 C O N

Message to this URL.

*Only applicable for browser

submission, optional. If not
sent in the request, NotifyUrl
that was stored in the
Merchant Profile during
registration will be used.

20 NotifyUrlParams Query String to be 255 C O N

appended to the Merchant
Notify URL.

44
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
21 PostUrl eNETS will post the 80 CC O O
transaction information to
the Merchant POST URL for
logging and inventory
update. This URL is not visible
to the shopper.

22 PostUrlParams Query String to be 255 CC O O

appended to the Merchant
Post URL.
23 CancelUrl URL to redirect to when 80 CC O O
shopper clicks cancel during
the payment process.

24 CancelUrlPara Query String to be 255 CC O O

ms appended to the Merchant
Cancel URL.
25 Stan Credit Note Number (must 6 CC O O
be unique for the same
batch)

# Mandatory for CAPTURE

and CREDIT transactions
only.
Fields 26 – 29 are applicable for 3D Secure transactions. Merchants who connect to a third-
party MPI for credit card number authentication may send the authentication results to
eNETS.
26 Cavv Cardholder authentication 28 CC C C
Verification Value.
Required when the value of
Transaction Status is "Y" or
"A".
27 purchaseXid Transaction Identifier 20 CC C C

45
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
28 Status Indicates whether a 1 CC R R
transaction qualifies as an
authenticated transaction.

Y = Authentication
Successful.
Customer was successfully
authenticated. All data
needed for clearing,
including the Cardholder
Authentication Verification
Value, is included in the
message.

N = Authentication Failed.
Customer failed
authentication. Transaction
denied.

U = Authentication Could
Not Be Performed.
Authentication could not be
completed, due to technical
or other problems.

A = Attempts Processing
Performed.
Authentication could not be
completed, but a proof of
authentication attempt
(CAVV) was generated.
29 ECI Electronic Commerce 2 CC C C
Indicator
30 Param1 Reserved 100 CC N O
Valid values:
- "RPP" (see section Error!
Reference source not found.
Error! Reference source not
found.)
- "RECURRING" (see section 5
Using UMAPI for Recurring
Transaction)

Note:
- Strings in uppercase
- "RPP" for specific
merchants only
- "RECURRING" for
merchants subscribed to
generic recurring
payment service.

46
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Paymen Inclusion
Length t Mode Credit Credit
Browser Server
31 Param2 Reserved (for RPP, see 550 CC N O
section Error! Reference
source not found. Error!
Reference source not found.)
Param3 Reserved 100 CC N O
32
Param4 Reserved 100 CC N O
33
Param5 Reserved 100 CC N O
34
ClientType Indicates what kind of 1 C O N
35
device the customer used
for the transaction.
W – From computer browsers
M – From mobile device or
tablet browsers/applications.

If not set, defaults to W.

Based on this, eNETS will

redirect customer to the
web (current) pages or
mobile pages accordingly.

Debit Payment Request

S/N Field Name Remark Max Length

1 NetsMid UMID (Universal Merchant ID). Uniquely identifies 20

merchant. Value assigned by eNETS.
2 Tid Terminal ID. Identifies the merchant terminal, if 20
applicable, from where transaction originates.
If not present in the request, eNETS will set the
Terminal ID to the IP address from where the
request originates.
3 TxnAmount Transaction amount in cents for all currencies. 10
E.g. for $10.00 in SGD, the TXN_AMT will be equal
to 1000. For ¥10,000 in JPY, the TXN_AMT will be
equal to 1000000.
4 CurrencyCode Identifies the type of currency used. Three- 3
character currency code following the ISO 4217
standard.
If not set, defaults to SGD.
5 MerchantTxnRef Unique reference code assigned by merchant 20
for this transaction.
6 MerchantCertId ID of the Certificate used for this transaction. It is 5
assigned by eNETS after merchant generates his
key pair and uploads the public certificate to
the gateway.
7 MerchantTimeZ A time zone is a region of the Earth that has 6
one adopted the same standard time, usually
referred to as the local time. MerchantTimeZone
means the time zone in which the Merchant is
located (e.g. "+11:30")
47
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
S/N Field Name Remark Max Length

8 merchant_txn_ Transaction Date (dd/mm/yyyy format) 10

date
9 merchant_txn_ti Transaction Time (hh:mm:ss format) 8
me
10 PaymentMode Payment method of the transaction 2
DD – Direct Debit
This field is required if the merchant does not
publish his collection page.
If not sent in the request, eNETS will redirect the
customer to the Merchant Collection Page to
select the payment mode.
11 SubmissionMod B – Browser Submission 1
e For Direct Debit payment, set to B.
12 ClientType Indicates what kind of device the customer 1
used for the transaction.
W – From computer browsers
M – From mobile device or tablet
browsers/applications.

If not set, defaults to W.

Based on this, eNETS will redirect customer to

the web (current) pages or mobile pages
accordingly.
13 Param1 Reserved Defined by user
14 Param2 Reserved Defined by user
15 Param3 Reserved Defined by user
16 Param4 Reserved Defined by user
17 Param5 Reserved Defined by user

48
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
2.4.9 Supplementary Message

Supplementary message is optional. If required, it shall be submitted together with the Credit
Payment Request.

S/N Field Name Remark Max Payment Inclusion

Length Mode Credit Credit
Browser Server
1 APC Additional processing code. 20 C O N
Allowed values:-
- “CCPrefix”

Note: Allowed values shall be

assigned by eNETS. Only
alphanumeric values are allowed
and no special characters allowed.
2 Delimiter Fixed as “:” 1 C O O
3 Data If APC = ”CCPrefix”, 500 C O O
this field shall contain, first
few digitis of a creditcard
number up to a maximum of
8 digits.

2.4.9.1 APC Field value equals to “CCPrefix”

If the eNETS Gateway receives a “CCPrefix” string in the APC field, it shall assume that the Data
field contains the first few digit of a credit card number up to a maximum of 8 digits. The eNETS
Gateway shall populates the Data field’s value onto the eNETS Creditcard Payment Page
Credit Card Number field, and subsequently presents it on the browser. The Data field’s value
populated on the eNETS Creditcard Payment Page Credit Card Number field is NOT editable.

49
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

3 Architecture
 Package Structure
 Main Components
 Functions
 Supporting files

3.1 Package Structure

The UMAPI is provided as a dynamic link library (dll), umapi.dll. The package structure is as
follows:

50
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
3.2 Main Components

Below are the descriptions for the main UMAPI components:

Component File Description

Name
Merchant Merchant is the base class where the specialised CreditMerchant,
DebitMerchant, and VAcctMerchant are subclassed. It provides merchants
with the methods to perform transactions, as described in Table 1 below.

For Credit Card transactions, CreditMerchant should be instantiated as

follows:
CreditMerchant m = (CreditMerchant) Merchant.getInstance
(Merchant.MERCHANT_TYPE_CREDIT);

For Direct Debit transactions:

DebitMerchant m = (DebitMerchant) Merchant.getInstance
(Merchant.MERCHANT_TYPE_DEBIT);
TxnReq TxnReq is the data class used to encapsulate the Payment Request
message, and provides getter/setter methods for setting the various fields in
the message.

Merchants need to pass the TxnReq object to the formPayReq/doPayment

methods.
TxnNotify TxnNotify is the data class used to encapsulate the Payment Notification
message.
TxnAck TxnAck is the data class used to encapsulate the Payment
Acknowledgement message.
TxnRes TxnRes is the data class used to encapsulate the Payment Response
message.
PGPHelper PGPHelper is the helper class used for performing PGP operations. It is used
internally for encrypting/decrypting the messages, and for
signing/verification of the message signatures.
HttpClient This is the class that acts as the Http Client, and is used internally to
establish the connection to eNETS server, for server-side submission mode.
Encryptor Utility class for encryption/decryption of sensitive data in NETSConfig.xml.

3.3 Functions

The unified merchant API enables merchants to perform transactions via credit card or direct
debit. It facilitates merchants with the functions described in Table 1 below.

Function Description
formPayReq Form a payment request message based on eNETS II message specifications.
The result is an encrypted string ready to be sent to eNETS II payment
gateway.
formAck Form an acknowledgement message based on eNETS II message
specifications. The result is an encrypted string ready to be sent to eNETS II
payment gateway.
doPayment Send out a payment request message to eNETS II payment gateway.
unpackNotificatio Unpack notification message from eNETS II payment gateway. It also decrypts
n and verifies the message.
51
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
unpackResponse Unpack payment response message from eNETS II payment gateway. It also
decrypts and verifies the message.
queryTxnStatus Query transaction status at eNETS II payment gateway.

Table 1 Unified Merchant API Functions

The eNETS payment gateway listens to HTTP request from merchants. The Unified Merchant API
gives merchants the flexibility of posting the message via API, or forming the message via API
but posting it in their preferred way. The two methods are further elaborated as follows:

 Use the ‘doPayment’ functions. Merchants only need to supply UMAPI with payment
information; UMAPI will form the message and send out to eNETS II payment gateway.
Merchants can also specify proxy server if necessary. This method takes care of the HTTP
post for merchants. It is simple and easy to implement.

 Use the ‘formPayReq’ / ‘formAck’ functions. Merchants supply UMAPI with payment
information and get a ready-to-send message from UMAPI; they then do their own HTTP
post to eNETS II. This method gives merchants the freedom of implementing their own
business logic, e.g. re-try mechanism after time-out, and using more advanced
technology, e.g. proxy authentication. It is more complicated and suitable for more
advanced merchants. Internally, ‘doPayment’ actually makes use of the ‘formPayReq’
function.

3.4 Supporting files

 log4net.dll-1.2.10
 SecureBlackbox.dll – 6.0.0.137
 SecureBlackbox.PGP.dll – 6.0.0.137

52
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
API installation and setup
This chapter contains the following sections:
 Pre-requisites for deploying UMAPI.
 Merchant Information Package
 Hosting of Domain Name / Internet Connectivity
 Server Setup
 Installation of UMAPI
 Generation of Public/Private key pair
 Encryption of Private key password
 Configuration of eNETS Merchant Admin
 Review of UMAPI Sample scripts
 Customisation of scripts by merchant
 Configuration of UMAPI Config files

3.5 Pre-requisites for deploying UMAPI

The merchant should meet, or have the necessary software / hardware as well as technical
support to meet all the pre-requisites stated in section 1.6 Pre-requisites for UMAPI Integration,
before progressing to further steps.

3.6 Merchant UMAPI Package

The NETS Merchant Technical Support team will provide the following information to the
merchant upon completion of registration formalities:

1. Merchant ID (unique field that identifies merchant).

2. Umapi.zip, containing the umapi library, supporting dlls and umapi configuration files.
3. OpenPGP certificate containing the Public Key of eNETS.
4. Sample script for integration
5. URL for merchants to submit their payment request to eNETS:
 Testing: https://test.enets.sg/enets2/PaymentListener.do
 Production: https://www.enets.sg/enets2/PaymentListener.do

3.7 Hosting of Domain Name / Internet Connectivity

Merchants need to have a valid domain name (e.g. www.abc.com) and public IP address, as
well as connectivity with the internet (typical implementation is subscription via a leased line
with an Internet Service Provider) for eNETS to communicate with them.

3.8 Server Setup

 OS support (supporting .NET Framework)

 Web Server
 Application Server (optional)

For internet transaction payments, merchants need to install a web server, develop a web site
with a payment checkout page (contains payment details, e.g. payment amount, goods /
services customer is paying for etc.), and ensure the web site has internet connectivity.

The use of an application server for internet transaction payments is optional. Security
requirements may require merchants to separate the web and application tiers into two
physical servers. 53
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

Merchants can perform the mandated actions above either by following the installation
instructions available in the accompanying technical guides or by engaging a vendor (system
integrator) to perform the job.

The merchant needs to install an operation system (OS) capable of supporting .NET Framework
1.1 or above.

3.9 Installation of UMAPI

The UMAPI comes in the form of a Winzip file (UMAPI.zip). Merchants need to extract the files to
a temporary directory, and copy the contents to the appropriate directories.

54
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
The UMAPI contains the following files:

Directory File Name File Description

etc nets-uat-full- OpenPGP certificate containing the Public Key of
pub.pgp.asc eNETS. It is used to encrypt the xml message during the
forming of the Payment Request/ Acknowledgement
message. It is also used for verifying eNETS signature
during the unpacking of the Payment Response /
Notification message.

Merchants have a choice of which directories they wish

to place the certificate in. However, the location
information of the certificate must be updated
nets-prod-full- accordingly in the
Same as above, UMAPI
but configuration
for PRODUCTION file.
environment. For
pub.pgp.asc production roll-in, merchant must replace the uat eNETS
public certificate with the corresponding production
certificate.
NETSConfig.xml Configurations file for UMAPI.NET. Refer to section 4.1.17
for more details.

Note:
The "etc" is defined in the following sample files:
a. Credit Browser: cc_browser_request02.aspx
b. Credit Server: cc_server_response.aspx
c. Debit: dd_browser_request02.aspx

Look for the following line and change the pathname

(eg "C:\\umapi\\webtest\\etc"):
myCreditMerchant =
(CreditMerchant)Merchant.getInstance(Merchant.MER
CHANT_TYPE_CREDIT, "C:\\umapi\\webtest\\etc")
bin log4net.dll Configurations file for log4net.
umapi.dll UMAPI dll, as described in section 3.1 Package
Structure. All the libraries are to be placed in your
application bin directory.
SecureBlackbox.dll Provides cryptographic protection for your data kept in
storage or during transfer across networks.
SecureBlackbox.PGP.d Cryptographic protection for PGP key
ll
PGPGeneratorApp.ex PGPGenerator will generate PGP keys
e
Encryptor.exe Password encryption.
Samples cc_server_request.asp
xcc_server_response.as
px
cc_browser_request.as
px
cc_browser_request02.
aspx
cc_browser_success.as
px
dd_browser_request.as
px
dd_browser_request02.
aspx
dd_browser_success.a
spx
query_status_request.a
spx
query_status_response.
aspx
55
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
3.10 Generation of Public/Private key pair

A toolkit is provided to the merchant to generate the PGP Keys. Launch the PGP KeyGenerator
application by executing the executable file PGPGeneratorApp.exe in the bin directory.

Figure 6. PGP Certificate Generator

The following inputs are required (all fields are compulsory):

Field Description
Selected directory Output directory for the generated key pair. The public key will be saved
as ddMMyyyyHHmmss-pub.pgp.asc and the private key as
ddMMyyyyHHmmss-priv.pgp.asc. It is advisable to rename the newly
generated files.
User Id Primary user id bound to the certificate.
Key Pass Passphrase for the private key.
Retype Key Pass Retype passphrase for the private key.
Expiry Date Format is dd/mm/yyyy.

After successfully generating the key pair, the following message will be displayed:

56
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

Figure 7. Certificate generation successful

57
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
3.11 Encryption of Private key password

The private PGP key generated in the previous step is protected by a key password. The key
password is stored in the merchKeyPass property in UMAPI configuration file NETSConfig.xml.
Merchants have the option of storing the password as clear text or in encrypted format.

A utility class is provided to the merchant encrypt to their key password using Triple DES
symmetric encryption.

Figure 8. Screen shot of text encryption of private key password

To invoke the utility, follow the steps below:

Run the executable file Encryptor.exe, passing in the text to be encrypted.

> Encryptor.exe encrypt "this is a test"

The following output will be generated:

Generating new secret key to umapikey.dat

Plain text: [this is a test]
Encrypted: [A16AD743D4B83F7964BDA316F1CD7155]

When this utility is run for the first time, it will generate a new secret key and save it to a file
called umapikey.dat.

The secret key can be copied to a directory of your choice. Subsequent usage of the utility for
encryption/decryption will make use of the generated secret key hence the location of the key
file needs to be specified in the configPath property in NETSConfig.xml.

Copy the encrypted text to the merchKeyPass property in NETSConfig.xml, and set the
encryption flag to true.

3.12 Configuration of eNETS Merchant Admin

Merchants need to log in to the administration module at https://test.enets.sg/enets2_admin/

to upload their public certificate generated in section 4.6 above.
58
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

For UMID, merchants should login with the login of individual MID (grouped under UMID) and
follow the same procedure as they perform for Credit/Debit MIDs. Also note that merchants
need to send a request to the eNETS Support Team to grant them access to the UMID Cert
Upload functions for UMID.

Merchant Administration URL:

 Testing: https://test.enets.sg/enets2_admin/
 Production: https://www.enets.sg/enets2_admin/

Note: If the menu items indicated on the left-hand side of the screen shot below does not
appear, merchants should contact eNETS personnel (see section 1.5 Contact Point) to
update their access rights.

3.12.1 Website URL

 Go to Merchant Admin -> Merchant Profile -> View Profile to check the current "Website Url"
setting.

Figure 9. Website Url

3.12.2 Public Key

 Go to Merchant Admin -> Public Key -> View Public Key to check the current Public Keys.

59
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

Figure 13. View Public Key

 Go to Merchant Admin -> Public Key Upload-> Request Public Key Upload, Click Submit

Figure 14. Request Public Key Upload

 Check email for password to upload Public Key

60
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

Figure 15. Example email for password to upload Public Key

 Go to Merchant Admin -> Public Key Upload-> Upload Public Key, enter password from
email, Click Submit. Click Choose File, select the Public Key file you generated for this MID,
click Submit.

Figure 16. Upload Public Key

 Go to Merchant Admin -> Public Key -> View Public Key to check the current Public Keys.
Record the "Cert ID" of the new Public Key uploaded. You will use the Cert ID in your code.

3.13 Configuration of proxy settings

If the merchant is using server-side submission and the merchant’s server is behind a proxy
server/firewall, the merchant needs to specify the proxy settings in NETSConfig.xml. Please refer
to section 3.14 Configuration of UMAPI Config files for the properties to set.

If the proxy server requires authentication, and merchant wants to store the proxy Password in
encrypted format, refer to section 3.14 Configuration of UMAPI Config files or instructions on
generating the encrypted password.

61
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
3.14 Configuration of UMAPI Config files

Configurations for UMAPI are stored in the file NetsConfig.xml, which contains the following
values:

Field Description
merchPrivKey Location of merchant private OpenPGP certificate
merchKeyPass Password for merchant’s private OpenPGP certificate
netsPubKey Location of eNETS public OpenPGP certificate
payURL eNETS server URL. Only applicable for server submission.
queryURL eNETS URL to query the transaction status
usePGP Must be set to true.
useProxy Applicable for server submission. If the merchant’s server is behind a proxy
server, set this flag to true.
proxyHost Proxy server IP
proxyPort Proxy server Port
proxyUsername Username for authentication to proxy server (if required)
proxyPassword Password for authentication to proxy server (if required)
encryption Flag to indicate whether the merchKeyPass and proxyPassword fields are in
clear text or encrypted format. Set to true to indicate that encryption is
turned on.
configPath If password encryption is turned on, this field specifies the folder containing
the secret key file. E.g. c:/umapiconfig/
TimeOut Connection expiry time.
logLevel Type of logging level to be set E.g. debug, info, error
logFile Path of log file (umapi.log) to be written on server.
protocol Protocol to be used E.g: "https"

3.14.1 Using Relative Path In UMAPI Config File

Merchant can choose to use the relative path instead of absolute path for below items in
UMAPI config file:
a) merchPrivKey
b) netsPubKey
c) configPath
d) logFile

In order to use relative path, merchant need to add one more parameter when instantiate a
Merchant object, where the parameter will be the starting path for the relative path.

New relative path instantiate method:

Merchant.getInstance(MERCHANT_TYPE, CONFIG_PATH, STARTING_PATH);
MERCHANT_TYPE Merchant type
CONFIG_PATH Path for NETSConfig.xml. Can be either relative path or absolute path.
STARTING_PATH The starting folder to be used for relative path

Sample of instantiate merchant using relative path, where the NETSConfig.xml stored in folder
D:\work\umapi.net\etc\config.

Merchant.getInstance(MERCHANT_TYPE, “.\\config”, “D:\\work\\umapi.net\\etc”);

Please note that if the merchant is using relative path but does not instantiate merchant object
with above new method, the starting folder will be vary based on the merchant application.
62 always be “%windir%\system32\inetsrv”.
For application host in IIS, the starting folder will
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

3.15 .NET UMAPI Strong Name Reference

For merchant need to reference to strong name umapi.dll, they can make the reference either
at compile time (early binding) or at run time.

3.15.1 Compile time reference

A compile-time reference occurs when you indicate to the compiler that your assembly
explicitly references another assembly. When you use compile-time referencing, the compiler
automatically gets the public key of the targeted strong-named assembly and places it in the
assembly reference of the assembly being compiled.
.
3.15.2 Run time reference
To make an assembly reference at run time, you must use the display name of the referenced
strong-named assembly. The syntax of a display name is as follows:

<assembly name>, <version number>, <culture>, <strong name>

Below is the sample of use this information with the Assembly.Load method
Assembly.Load(“umapi, Version=1.1.3.0,Culture=neutral,PublicKeyToken=28b77be8188e5cb8”)

Merchant can print the hexadecimal format of public key token for a specific assembly using
the following Strong Name tool (Sn.exe, which can be found in .NET SDk folder) command:

sn —Tp umapi.dll

63
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

4 Develop Scripts

4.1 Review of UMAPI Sample scripts

The merchant should look through the UMAPI sample scripts provided by eNETS, and
understand how the scripts work together to form a payment process with eNETS.

4.2 Customisation of scripts by merchant

The merchant should customise the sample UMAPI scripts provided by eNETS according to their
business and technical requirements.

Additional checks and database updates prior to composing the payment request message or
responding to a notification message may be added where appropriate.

5 Using UMAPI for Recurring Transaction

To send a Recurring transaction payment request, the merchant needs to embed the Recurring
parameter in the credit payment request message formatted through UMAPI before sending to
eNETS payment collection page. The additional field in the message which represents the
Recurring transaction is the field Param1.

5.1 Sample code

The following ASP .NET code fragment illustrates the additional requirements on formatting the
credit payment request message.

<%@ Page Language= »C# » AutoEventWireup= »true » %>

<%@ Import Namespace= »com.wiz.enets2.transaction.umapi » %>
<%@ Import Namespace= »com.wiz.enets2.transaction.umapi.data » %>
<%
String rpiDetails = null ;
…
TxnReq myTxnReq = null ;
CreditTxnReq myCreditTxnReq = null ;
…
myTxnReq = new TxnReq() ;
…
myCreditTxnReq = new CreditTxnReq() ;
…
myCreditTxnReq.setParam1(« RECURRING ») ;
…
myTxnReq.setCreditTxnReq(myCreditTxnReq) ;
myTxnRes = myCreditMerchant.doPayment(myTxnReq) ;
…
%>

64
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

6 Using UMAPI for IAP Transaction

To send an IAP transaction payment request, the merchant needs to embed the IAP
parameters in the credit payment request message formatted through UMAPI before sending
to eNETS payment collection page. The additional fields in the message which represents the
IAP transaction are fields Param1 and Param2.

Merchants who wish to use the Airline program should pass in param1 as “IAP” and param2
with Airline Ticket Number in UMAPI message.

<%@ Page Language= »C# » AutoEventWireup= »true » %>

<%@ Import Namespace= »com.wiz.enets2.transaction.umapi » %>
<%@ Import Namespace= »com.wiz.enets2.transaction.umapi.data » %>
<%
String rpiDetails = null ;
…
TxnReq myTxnReq = null ;
CreditTxnReq myCreditTxnReq = null ;
…
myTxnReq = new TxnReq() ;
…
myCreditTxnReq = new CreditTxnReq() ;
…
myCreditTxnReq.setParam1(« IAP ») ;
myCreditTxnReq.setParam2(<Airline Ticket number>) ;

…
myTxnReq.setCreditTxnReq(myCreditTxnReq) ;
myTxnRes = myCreditMerchant.doPayment(myTxnReq) ;
…
%>

65
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

7 Using Credit Payment Request with Supplementary Message

To send a browser-to-server Credit Payment Request message with a supplementary message,

the supplementary message shall be embedded in the same html redirection form post as the
credit payment request message. The supplementary message shall be the value of an html
variable named “supmsg”.

7.1 Sample code

The following ASP .NET code fragment, illustrates the sending of suppliementary message
togother with the associated credit payment request message.

<%@ Page Language="C#" AutoEventWireup="true" %>

<%@ Import Namespace="com.wiz.enets2.transaction.umapi" %>
<%@ Import Namespace="com.wiz.enets2.transaction.umapi.data" %>
<%@ Import Namespace="com.wiz.enets2.transaction.umapi.logging" %>
<%
string messageS = "", urlS = "", supMsgS;
CreditMerchant myCreditMerchant = null;
CreditTxnReq myCreditTxnReq = null;
TxnReq myTxnReq = null;

myCreditMerchant =
(CreditMerchant)Merchant.getInstance(Merchant.MERCHANT_TYPE_CREDIT,"c:\\umapi\\etc\\");

myTxnReq = new TxnReq();

myCreditTxnReq = new CreditTxnReq();

myTxnReq.setTxnAmount(Request.Form["txn_amount"]);
myTxnReq.setSuccessUrl(Request.Form["success_url"]);
myTxnReq.setFailureUrl(Request.Form["failure_url"]);
...

myTxnReq.setCreditTxnReq(myCreditTxnReq);

messageS = myCreditMerchant.formPayReq(myTxnReq);

supMsgS = "CCPrefix:42681234";
%>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-

transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>
<title>UMAPI .NET Test</title>
</head>
<body>
<form id="form1" method="post" action="<%= urlS %>">
<input type="hidden" id="message" name="message" value="<%= messageS %>" />
<input type="hidden" id="supMsg" name="supMsg" value="<%= supMsgS %>" />
</form>
<script type="text/javascript" language="javascript">
document.forms[0].submit();
</script>
</body>
</html>

66
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual

8 Response codes

eNETS Gateway will return the response code for the transaction in field netsTxnRespCode of
the Payment Response Message.

For Credit transactions, the response code can either be a two-digit number returned from the
merchant’s acquiring host or a four-digit number which indicates an error response from eNETS
Gateway.

For the online transaction status query feature, the response returned to the merchant is in the
format of <stage>_<responsecode>.

A.1 Credit Transaction Stages

Module Stage Code Stage

UMI 2001 STAGE_UMI_TRANSLATOR: From merchant to eNETS
2002 STAGE_UMI_PAYMENT_LISTENER: From merchant to eNETS, stage
at which the server decrypts the incoming message and verifies
the merchant signature
2004 STAGE_UMI_MERCHANT_COLLECTION: Merchant Collection stage
2005 STAGE_UMI_PAYMENT: stage at which the txn req message has
been successfully validated.
2006 STAGE_UMI_VALIDATION: validation of txn req message
CREDIT 1001 STAGE_CREDIT_VALIDATION: Validation of credit related
parameters
1002 STAGE_CREDIT_TO_COMMS: From eNETS to HOST
1003 STAGE_CREDIT_FROM_COMMS: From HOST to eNETS
UMID 3001 STAGE_UMID_MESSAGE: UMID Message received
3002 STAGE_UMID_MESSAGE: Selected Service received

A.2 Credit Acquirer Response Codes

The following table shows the different values that will be returned by the Acquirer Host in field
39 of the host response message.

Response Code (P-39) ISO8583 Definition

00 Approval
01 Refer to Card Issuer
02 Refer to Card Issuer’s Special Condition
03 Invalid Merchant
04 Pick-up
05 Do not honour
08 Approved, Verify ID & Signature
12 Invalid transaction
13 Invalid amount
14 Invalid card number
19 Re-enter transaction
21 No Transaction
25 Unable to locate record on file
30 Format error
31 Bank not supported
67 by switch
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Response Code (P-39) ISO8583 Definition
41 Lost card
43 Stolen card, pickup
51 Insufficient funds
52 No cheque account
53 No savings account
54 Expired card
55 Incorrect PIN
56 No card record
58 Transaction not permitted to terminal
61 Exceeds withdrawal amount limit
63 Security violation
75 Allowable number of PIN tries exceeded
76 Invalid product code
77 Reconcile error
78 Trans. Number not found
79 Batch already open / Invalid CVV2/CVC2
80 Batch number not found
85 Batch not found
88 Approved, Have cm call AMEX
89 Bad terminal ID
91 Issuer or switch is inoperative
94 Duplicate transmission
95 Reconcile error. Batch upload started
96 System malfunction

Note: Response Code returned by different acquirer bank may have different meaning.

A.3 Credit Response Codes

Error Code(-ve) Error Message

1000 Missing NetsMid
1001 Invalid NetsMid
1002 Invalid Merchant Id
1003 Merchant is not registered
1004 Merchant is not active
1005 Invalid Terminal Id
1006 Invalid Payment Mode
1007 Missing Txn Amount
1008 Invalid Txn Amount
1009 Invalid Currency Code
1010 Missing Merchant Reference
1011 Invalid Merchant Reference
1012 Invalid Merchant Txn Date Time
1013 Invalid Submission Mode
1014 Invalid Merchant Cert ID
1015 Invalid Credit Card Number
1016 Missing Credit Card Number
1017 Invalid Expiry Date
1018 Missing Expiry Date
1019 Invalid CVV/CVC2
1020 Invalid Card Holder Name
68
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Error Code(-ve) Error Message
1021 Missing Payment Type
1022 Invalid Payment Type
1023 Invalid Success Url
1024 Invalid Success Url Params
1025 Invalid Failure Url
1026 Invalid Failure Url Params
1027 Invalid Notify Url
1028 Invalid Notify Url Params
1029 Invalid Cancel Url
1030 Invalid Cancel Url Params
1031 Invalid Post Url
1032 Invalid Post Url Params
1033 Invalid Stan
1034 This page is currently UNDER CONSTRUCTION. Please try again later.
1035 Invalid UMID
1036 Invalid Client Type
1100 Malformed XML Input
1101 Invalid XML Schema
1102 Schema Validation Error
1103 PGP Error
1104 Unable to Sign With PGP
1105 Unable to Encrypt With PGP
1106 Unable to Decrypt With PGP
1107 Unable to Verify Signature With PGP
1108 Invalid PGP Signature
1109 XML Utility Error
1110 Unable to Generate Transaction Reference
1111 Merchant Not Subscribed to This Service
1112 Payment Mode Not Supported
1113 Unable to Decode
1114 Unable to Encode
1115 Unable to Format Merchant Message
1116 Invalid Certificate ID
1117 Merchant not subscribed to recurring payment service
1118 Merchant not subscribed to instalment payment service
1119 Invalid instalment period
1120 Merchant not subscribed to IAP payment service
1200 Invalid login
1201 Error retrieving customer info
1202 Credit Card Number not allowed
1203 Credit Card Expired
1204 Transaction Amount not within allowed range
1205 Reversal Amount not equal to original amount
1206 Capture Amount more than original Authorisation amount
1207 Credit Amount more than original Sale/Capture amount
1208 Transaction Not Allowed
1209 Batch Close in Progress
1210 Bank not active
1211 BITMAP ERROR
1212 Reversal not allowed in different batch
1213 No Mapping found for Txn Type
1214 Unknown Merchant Type
1215 Error getting HostMID 69

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
Error Code(-ve) Error Message
1216 No acquiring bank found
1217 No HostTID configured for merchant
1218 Host Mid not found in database
1219 Host Tid not found in database
1220 Error occurred during batch close
1221 Error instantiating processor
1222 Transaction does not exist
1223 Duplicate transaction (Applicable to UMID duplicate transactions also)
1224 Transaction being processed
1225 Transaction has already been reversed
1226 Transaction has already been credited
1227 Transaction has already been captured
1228 Transaction has already been charged back
1229 Transaction Locked
1230 Transaction has already been cancelled
1231 System Error
1232 System Error
1233 System Error
1234 Transaction does not exist
1235 Recurring transaction not allowed (applicable to OCBC AUTH
transactions)
1290 Comm channel type not defined
1291 Comm channel info not defined
1300 Comms Timeout
1301 Comms Error
1302 Merchant bank is under maintenance.
1401 Stan does not tally with request
1402 Terminal ID does not tally with request
1403 MTID does not tally with request
1404 Missing Response code
1405 Unable to parse response
1501 Cannot Notify Merchant. Contact eNETS
1502 Cannot Notify Merchant. Contact eNETS
1503 Cannot Notify Merchant. Contact eNETS
1504 Cannot Process Transaction. Contact Merchant
1505 Reversal failed
1600 EzProtect parameters are required
1601 Product details are required
1602 Product format is required
1603 Shopper IP address is required
1604 Billing First Name is required
1605 Billing Last Name is required
1606 Billing Address is required
1607 Billing City is required
1608 Billing State required
1609 Billing Zip Code is required
1610 Billing Country is required
1611 Billing Phone is required
1612 Billing Email is required
1613 EzProtect Risk Threshold is exceeded
1614 Error occurred with the EzProtect service
1700 Error in determining enrolment/3D transaction status
1701 Card not enrolled 70
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Error Code(-ve) Error Message
1702 Authentication failed
1703 Unable to connect to ParesListener
1704 Card Type not recognised
1705 Acquirer not 3D secure enrolled
1706 Merchant not 3D secure enrolled
1707 Acquirer’s password missing
1708 Acquirer’s password is invalid
1709 Invalid currency code
1710 Invalid transaction data
1711 PAReq not received by ACS
1712 Cannot find serial number
1713 Invalid 3D merchant Id
1714 Invalid credit card number
1715 Invalid credit card expiry date
1716 Invalid order number
1717 Invalid purchase amount
1718 Recurrence frequency is invalid
1719 Authorisation number is invalid
1720 Card not supported
1721 Validation Error
1722 3D processing error. Kindly contact your issuing bank to investigate
1723 System Error during Secure3D authentication
1799 MPI timed out
1901 Referring page does not match ‘referrer URL’ in merchant profile.
1902 User Timeout
2000 A System Error occurred
2001 A Database Error occurred
2002 Invalid Session. Please contact Merchant to check your transaction status.
2003 Txn cancelled at service selection page (UMID)
2005 Credit card prefix not valid
4035 Transaction Failed. Please try again.

A.4 Debit Transaction Stages

Stage Code Stage Description

000001 Payment Request from eNETS II to Bank Host
000002 Notification from Bank Host to eNETS II
000003 Acknowledgement from eNETS II to Bank Host
000004 Txn End from Bank Host to eNETS II
000005 Payment Request from Merchant to eNETS II
000006 Notification from eNETS II to Merchant
000007 Acknowledgement from Merchant to eNETS II
000008 Txn End from eNETS II to Merchant

A.5 Debit Acquirer Response Codes

A.5.1 Successful Transaction

Code Error Description Reasons Action

00000 Transaction Successful Merchant to proceed with
71
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
fulfillment of order.

Note: Full response code

should be 000008_000000

Note to merchants using

QUERY function:
- 000004_000000 is also
considered as successful
transaction

A.5.2 Bank Related Response Codes

Code Error Description Reasons Action

20001 Internal System Error Internal processing errors If Gateway returns this status
such as Database for Notification
unavailability and network Acknowledgement
problem, etc. Message, the Bank will have
to initiate a reversal of the
transaction.
20002 Data Validation Error Invalid data sent from The bank will not proceed
either party with the transaction and will
initiate a reversal. It will
inform customer the
transaction is unsuccessful.
20003 XML Related Error Either XML parsing error or If Gateway returns this status
invalid/missing DTD etc. for Notification
Acknowledgement
Message, DBS will have to
initiate a reversal of the
transaction.
20004 Transaction Failed Transaction is not Customer will be notified of
successful, due to reasons the status and be
such as customer has redirected back to the
entered invalid PIN or Merchant page.
insufficient funds, etc.
20005 Communication Errors Open connection type of For notification message,
errors, broken pipe errors or the Bank will retry a
time out errors. configurable number of
times.
20006 Digital Certificate Errors Either party’s certificate is The Bank/Gateway will not
either expired or invalid. accept the message and if
the notification message
has already been sent, the
Bank will initiate a reversal.
20007 Invalid digital Signature Verification of either party’s The Bank/Gateway will not
signature failed. accept the message and if
the notification message
has already been sent, the
Bank will initiate a reversal.

72
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Code Error Description Reasons Action
20008 Session Errors Time out due to customer Customer will not be
inactivity. allowed to proceed and will
be informed that his/her
session has expired. They will
then be redirected back to
the Merchant site.
20009 Bank API configuration Inform Banks to reconfigure
error API.
20010 Failed to receive Check Gateway.
acknowledgement
from Gateway
20011 No match for Gateway Double check Gateway
public certificate. public certificates.

A.5.3 Gateway Related Response Codes

Code Error Description Reasons Action

30001 Merchant not found in No merchant record in the Check Gateway database.
Merchant_Profile table merchant_profile table.
30002 Merchant Failure_URL Check Gateway database.
not found in
Merchant_Notify_URL
table.
30003 Unable to retrieve Check Gateway database.
Merchant’s Public key
from Merchant_Cert
table.
30004 Signature Error Unable to verify Merchant Merchant to check that the
signature due to different public key sent to the
keys used. Gateway is correct.
30005 Duplicate Transaction The payment request Merchant to advise
consists of a Merchant customer to wait before
reference code that was trying again.
used before.
30006 Merchant Ref Code Merchant to advise
generated is not customer to wait before
unique. trying again.
30007 Unable to insert Check gateway database.
transaction to
MerchantArchive
table.
30008 Unable to save Check gateway database.
transaction to
ASPArchive table.
30009 Unable to insert Check gateway database.
transaction into
Merchant_Txn_Info and
Merchant_DD_Txn_Info
tables.
30010 Unable to insert ASP Txn Check gateway database.
Time into ASP_Txn_Info
table.
30011 Unable to generate Merchant should check the
gateway signature 73 public key of Gateway.

eNETS .NET Merchant Integration Guide

GENERAL
UMAPI .NET Merchant Integration Manual
Code Error Description Reasons Action
30012 Bank ID not found. Transaction cancelled by Merchant can show the
user at Gateway’s Bank same payment page again.
selection page.
30013 Bank ID not enabled Fill in the problem log and
escalate to eNETS.

30014 Client-side HTTP error Check Gateway HTTP.

when notifying
Merchant.
30015 Server-side HTTP error Check Gateway HTTP.
when notifying
Merchant.
30016 Merchant Notification Merchant’s notification
Acknowledgement acknowledgement
Timeout received later than
expected turnaround time.
30017 Exchange Rate does Required for currency Contact RBS and/or verify
not exist (Forex Debit) conversion Rate Retrieval from
FXmicropay
30018 Invalid Exchange Rate Required for currency Contact RBS and/or verify
(Forex Debit) conversion Rate Retrieval from
FXmicropay
30019 System does not allow Transaction rejected by Check Gateway Database
transaction to be switch during initial stage.
processed Possible causes:
- profile is not active
- amount not in range,
- invalid merchant
- invalid currency
- invalid payment mode
- invalid bank id
40001 Unable to retrieve Check Gateway database.
Bank’ URL from
Bank_Profile table.
40002 Merchant Ref code Check that BankMgr is
gotten from Bank is null. running.
40003 Unable to retrieve Check Gateway database.
Bank’s Public key from
Database
40004 Unable to verify Bank The Gateway will not
Signature. accept the message.
Check with the respective
bank.

40005 Unable to save Txn End Check Gateway database.

html to BankArchive
table.
40006 Unable to save Txn End Check Gateway database.
html to ASPArchive
table.
40007 Unable to insert Check Gateway database.
transaction into
Log_Merchant_Trans_E
nd table.
74
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Code Error Description Reasons Action
40008 Unable to update status Check Gateway database.
in Merchant_Txn_Info
table.
40009 Unable to retrieve Check Gateway database.
Merchant_URL in
Merchant_Notify_URL
table.
40010 Duplicate Txn End The payment request Bank to advise customer to
consists of a bank wait before trying again.
reference code that was
used before.
40011 Transaction timeout The Gateway has no Check Gateway itself and
response in specified time. link between Gateway and
bank.
40012 Gateway private key
has been revoked
40013 Bank private key has
been revoked
40014 Merchant private key
has been revoked.
40096 System Error
40097 Transaction Not Found
40098 Transaction is not in a Stage response code does Check gateway database
valid state for this not align with the
action. transaction status.
40099 Transaction Transaction cancelled by Merchant can show the
Unsuccessful user at Gateway’s Bank same payment page again.
selection page.

A.5.4 System / Application Related Response Codes

Code Error Description Reasons Action

50001 Registry Access Error Fill in the problem log and
escalate to eNETS
50002 Database Access Error Fill in the problem log and
escalate to eNETS
50003 Page forward Error Fill in the problem log and
escalate to eNETS
60001 Unable to get the CRL Fill in the problem log and
escalate to eNETS.
60002 Unable to send e-mail Fill in the problem log and
to Administrator escalate to eNETS.
60003 Unable to validate the Fill in the problem log and
merchant Certificate escalate to eNETS.
60004 Unable to update Check the database.
revoked flag in
database for
Merchants
60005 Unable to validate the Fill in the problem log and
Gateway Certificates escalate to eNETS.
60006 Unable to update Check the database.
revoked flag in
database for Gateway
75
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Code Error Description Reasons Action
60007 Unable to validate the Fill in the problem log and
Bank Certificates escalate to eNETS.
60008 Unable to update Check the database.
revoked flag in
database for Banks
60009 No certificate Authority Fill in the problem log and
ID specified escalate to eNETS.
70001 Unable to connect to Double check password.
the Password Server
70002 Invalid database Key into the correct
password password.
70003 Failed to check Fill in the problem log and
connection to the escalate to eNETS.
database
80001 Error loading data into Fill in the problem log and
context escalate to eNETS.
90001 Invalid URL for reloading Fill in the problem log and
data into context escalate to eNETS.

A.5.5 Merchant Related Response Codes

Code Error Description Reasons Action

1001 Wrong merchant or SS should check whether
this merchant’s records are
customer identification.
in the database or not.
1002 Wrong bank PIN keyed- User should key in again.
in by user.
1003 Internet Banking SS should check with the
transaction failed. Bank.
Please check with the
Bank concerned.
1004 Session timeout. Transaction has taken too Customers will not be
long or user is inactive for allowed to proceed and will
too long be informed that their
session has expired. They will
then be redirected back to
the Merchant site.
1005 Database access error. Check Gateway database.
1006 Error in re-direction of Check Gateway
web page. connection with Banks or
Merchants.
1007 Invalid digital signature. Verification of Gateway The Gateway will not
signature failed accept the message.
1008 Network error. Check Gateway network.
1009 Unable to connect to Call respective bank to
check his bank.
bank server.
1010 Error due to user PC Nil
shutdown
unexpectedly.

76
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Code Error Description Reasons Action
1011 User cancelled Nil
transaction before
completion.
1035 Invalid UMID

77
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Appendix B Change History
.NETS Version

Version No. Revision No. Description Approval

Date
1 0 Initial Document 23 Dec 2005

1 1 Section 2.3.2, Added “customAttribute” field to the 13 Apr 2006

Payment Response Message
Section 4.1.11, password encryption in
“NETSConfig.xml”
Section 4.1.13, support for proxy server
Section 4.1.14, importing of CA root certificate
Section 4.1.9, installation and static registration of the
“cryptix jce” and “openpgp” providers
Section 2.3.1, Added fields param1, param2, param3,
param4 and param5 to Payment Request Message
Section 5, list of response codes
1 2 Added new Section on using UMAPI for “RPP” 4 Oct 2006
transaction.
1 3 Add sample codes for debit transactions & server-to- 14 Dec 2006
server response
1 4 Add Debit Stage Code 18 Dec 2006

1 5 Amended samples codes for credit and debit txns. 20 Dec 2006

1 6 Amended section 2.3 04 Jan 2007

1 7 Amended section 2.3 11 Jan 2007

1 8 Added sample code for querytxnstatus 21 Mar 2007

1 9 Amended the direction of flow 2 & 3 in Section 2.2.2 30 Mar 2007

Amended email from [email protected] to
[email protected] in Section 1.5
1 10 Added Staging URL in Section 4.1.2 02 Apr 2007

1 11 Amended section 2.3.4 and 4.2.1.2 for 3D Secure 10 Apr 2007

handling.
1 12 Added in Appendix A & Reference document 20 Apr 2007

78
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Version No. Revision No. Description Approval
Date
1 13 Updated Section 2.2.2.2 – Updated descriptions for 06 Jul 2007
step 3 and 4.
Updated Section 2.3.4 – Added 5 as a new status for
netsTxnStatus field.
Updated Section 2.3.1 – Updated description for field
TxnAmount
Updated Section 2.3.2 – Updated description for field
TxnAmount
Updated Section 2.3.4 – Updated description for field
netsAmountDeducted
Updated Section 2.3.5 – Updated description for field
TxnAmount
Updated Section 2.3.6 – Updated description for field
TxnAmount
Added in Section 6 – Added response code 1234
1 14 Amended error codes in Section 6.
Added in Section 6 – Added response code 1302
1 15 Add the merchant-date-time, merchant code for May 2008
debit pay request
Add Note to identify notify and TxnEnd URL to be
implemented in Debit Flow.
Update 3-D transaction flow.
Add the cancel status for the cancelling of
transaction.
1 16 Added the .NET version of UMAPI

1 17 Update the NetsTxnRespCode field for credit 25 August

response to 2008
length of 5
Update the NetsTxnstatus field for credit response to
length of 4

To add the TxnAmount field in the debit response

message

Remove Debit success/failure/cancel/notify URLs in

debitReq XML message in Appendix A
1 18 To add to the sample code to read the TxnAmount 31 August
for debit response. (Section 4.2.1.3.2) 2008

To remove comment of MerchantTimeZone,

merchant_txn_date, and merchant_txn_time fields in
the debit payment request message.(Section 4.2.1.3)

To add two fields to submit paymentMode and

submissionMode in debit payment request message
format. (Section 2.3.5)

79
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Version No. Revision No. Description Approval
Date
1 19 To add on the sample code on debit 12 September
notification/acknowledge process to read the 2008
notification message parameter from eNETS. (Section
4.2.1.3.3)
1 20 Section 2.3.8 Update the length of netsresponse 23 September
code.

Section 2.3.8 Update the nets-txn-msg not include in

the during transaction end server-to-server

Section 4.2.1.3.3 Update sample code to get

txnAmount using getTxnSrcAmt();

1 21 Section 2.3.2 26 September

Update comment of the netstxnstatus and the
maximum length to 5.

Section 2.3.4
Update the comment on netsTxnRespCode.
1 22 Section 2.3.1 14 October
To add the field length for CAVV, purchaseXID, status,
ECI

Section 2.3.4
Update the comment on netsTxnRespCode.
Added a new column to show the inclusion for
browser-to-server and server-to-server transactions.

Section 4.2.1.1.1
To add the sample code to set MerchantTxnDtm for
Credit Payment Request

Section 4.2.1.1.2
To add the sample code to get PaymentMode for
Credit Payment Response

Section 4.2.1.1.3
To add sample code for to get payment mode,
submission-mode, txn-Amount, merchantTxnDtm,
netsTxnDtm and netsTxnStatus.

Section 6.1
Grouped the table per category of response codes.
1 23 Section 2.3.6 Debit Payment Notification 23 Nov 2008
Remove PaymentMode, SubmissionMode,
netsTxnDtm.
Add Dest_exchg_Rate, GW_Txn_Date, GW_Txn_Time,
Bank_ID, Bank_Ref_Code, Bank_Status,
Bank_Time_Zone, Bank_Txn_Date, Bank_Txn_Time,
Bank_Remarks, Retry, version and reserved
parameters.

80
Section 2.3.8 Debit Payment Response
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Version No. Revision No. Description Approval
Date
Rename netsTxnDate to GW_Txn_Date.
Rename netsTxnTime to GW_Txn_time.
Add Bank_time Zone, GW_Time_zone,
Dest_Exchg_Rate, Dest_Curr_Code, Src_Txn_Amt,
Src_Exchg_Rate, Src_Curr_Code, Retry, version and
reserved parameters

Section 4.2.1.3.2
To add sample code

Section 4.2.1.3.3
To add sample code
1 24 Section 2.3.7
To remove the netsCertID from acknowledge
message

Section 4.2.1.3.3
To remove the setting of netsCertID from sample
code
To add the code to set the merchantCertID
1 25 Updated and changed manuals style and formatting
Updated information on different areas
Update credit acquirer response code “79”
Updated date and time format
1 26 Update the format of merchant transaction date in
section 2.3.5
1 27 Updated sections 2.3.6 (Field 21)and 2.3.8 (Fields 7 21 Dec 2010
and 10) remarks for informational fields.
1 28 Amended contact details in section 1.5. 04 Mar 2011
o Address from Motorway Building to Central Plaza.
o Email address from
[email protected] to
[email protected]
o Added hotline number 65) 6274 1212 and
operating hours.
1 29 - Updated section 2.3.6, remark column of field 12: 11 Apr 2011
Notification.netTxnStatus is an intermediate status
and SHALL NOT be used by merchant for
processing.
- Updated section 2.3.8, remark column of field 5:
Field contains the final transaction status.
1 30 - Updated section 2.3.4, “Max Length” of “Pareq” 20 May 2011
field set to “-“
- Updated section 4.1.8 Installation of policy JARs 08 June 2011
for JDK 1.5 & 1.6
1 31 - Updated Table of content, section 8 is included. 07 Sept 2011
- Updated section 2.3.1, added new fields to table
related to RPP & RECURRING
- Updated section 6, new eNETS credit response
code 1117 is added.
- Added new section 8, Using UMAPI for Recurring
transaction, note that section numbers of
following this section are changed.
81
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Version No. Revision No. Description Approval
Date
1 32 - Updated section 4.1.17, added 3 new fields 27 Oct 2011
TimeOut, logLevel, logFile, protocol which are to
be added to configuration file “NetsConfig.xml”

1 33 - UMID changes (updates to Section 1.4, Section 30 Nov 2011

4.1.12, Section 4.2.2, Section 5, Section 6, Section
6.1, Section 8 & New Section 2.3.9)
2 - Revision of Manual 13 Oct 2014

2 1 - Change section B.1.1 to section B.1.2 22 Jul 2013

- Change section B.3.1. to section B.3.2
- Added section B.1.1, Credit Card Browser Request
- Added section B.3.1, UMID Browser Request
- Sample code updated for Section B.1.1, Section
B.1.2, Section B.1.3, Section B.1.4, Section B.1.6,
Section B.1.7, Section B.1.8, Section B.1.9, Section
B.2.1, Section B.2.2, Section B.2.3, Section B.2.4,
Section B.3.2, Section B.3.3
2 2 - Updates for IAP enhancement (updates to 14 Nov 2013
section 2.4.1, Appendix A.3 & New section 8)
2 4 - Added section 4.11 for .NET UMAPI stong name 28 Apr 2014
reference
2 5 - Added section 4.10.1 for .NET UMAPI using relative 2 Oct 2014
path in NETSConfig.xml
2 6 - Removed “Direct HTTPS requests” from section 2.1 15 Sept 2015
and 2.2
- Updated section 2.2.3.2 diagram with Stage code
- Updated section 2.4.4 netsTxnStatus descriptions
and footer format
- Updated section 4.2 with one added point on
sample script request
- Removed “Update Profile” from section 4.8.1
- Removed section 4.8.2 and 4.8.3 for logo update
and redirection URL update
- Removed section 5 for RPP Transaction
- Removed section 8 for Query Txn
- Updated section A.4, removing module column
and updated Stage column name
- Updated section A.5, action descriptions
- Removed section A.5.5 Note
- Removed section Appendix B and Appendix C

82
eNETS .NET Merchant Integration Guide
GENERAL
UMAPI .NET Merchant Integration Manual
Version No. Revision No. Description Approval
Date
2 7 - Updated section 1.6(Pre-requisites for UMAPI 1st March 2016
Integration) with the following items :
 4. Static IP Address
 5. Merchant SSL Certificates
- Updated section 2.4.1 on supplementary
message.
- Added section 2.4.9 (Supplementary Message).
- Added new section 8 (Using Credit Payment
Request with Supplementary Message.
- Update Appendix A.3 Credit Response Codes to
add new Response Code 2005
- Added section 6 – UMAPI for Recurring
Transaction
- Rename section 6 to 7
- Rename section 7 to 9
2 8 - Updated the table in section 2.2.1 on Notification 8th Sep 2016
and Notification Acknowledgement messages
- Updated section 2.4.3. Remove Transaction
Rejection Code & Merchant Internal Error, Invalid
messages