Network Online Electronic and Mobile-commerce Platform

Transcription

1 Network Online Electronic and Mobile-commerce Platform Web Service Query and Reversal API Integration Document Version 2.0 October, 2014

2 Contents Contents... 2 Copyright... 3 Preface... 4 Purpose... 4 Audience... 4 Related Information... 4 Conventions... 4 Executive Summary... 5 About Network International... 5 Introduction... 6 About this Document... 6 Overview... 7 Getting Started with Web Service API... 8 Communicating with Network Online... 8 Query API Overview Request fields Response Fields...11 Reversal/Capture API Overview Request and Response Fields SPECIAL CHARACTERS Web Service Formats and Examples Query Request Format Query Response Format Full Auth Reversals API Request Format Full Auth Reversals API Response Format Encryption and Authentication Test Merchant Encryption / Decryption Key Production Merchant Encryption / Decryption Key How to use encryption or decryption Error Codes NeO Error Codes Payment Gateway Error Codes

3 Copyright 2014 Network International Published August, 2014 Network International reserves all the rights to this publication. The information provided in this document is subjected to change without any notice. Network International is not responsible for any warranty or responsibility related to the information in this document. Distribution, copying or reproducing any part of this content or any information about the applications without the consent of Network International is strictly prohibited. 3

4 Preface Purpose This integration guide describes how to use Web Service API with the Network Online platform. Audience This document is intended for Network Online merchants who will be communicating with the Network Online platform using Web Services API. Related Information For information related to Network Online Electronic and Mobile-commerce Platform for re-direction model, refer to the respective Integration Guide. Conventions The special conventions used in this document are as follows: Note: Note represents information that needs to be noted and may be useful. IMPORTANT An important notice represents information that is essential and needs to be performed. 4

5 Executive Summary About Network International Network International (NI) is the largest payment processing service provider in the United Arab Emirates (UAE) and has operations across the Middle East and North Africa (MENA) region. NI supports acquiring and issuing banks with a range of payment products and services and with end-to-end solutions for customer acquisition, management or servicing functions. Merchant acquiring and processing, ecommerce services, fraud management, mobile solutions for payment industries are some of them. NI is the largest E-Commerce provider in the UAE. The 700 E-Commerce merchants associated with NI aim to process USD 2.5BN in online value in 2013 and over $3BN in

6 Introduction About this Document Network Online Electronic and Mobile-commerce Platform facilitates merchant integration either through APIs or NI hosted solutions. The scope of integration for the merchants includes transaction, reversals and query processing. For functionalities that do not require integration, including reporting, reconciliation and advanced fraud capabilities, you can refer to the respective documentation. This document describes the Web Services API. This Application Programming Interface enables you to connect your application to the payment gateway and provides the flexibility and ease of integration. The Web Services technology supports the independence of platform and programming language. Web Services API comprises operations that can be executed through welldefined XML messaging, with the appropriate WSDL files. With Network Online Web Services API, you can do the following: Connect directly with the Network Online server to send a query related to a particular transaction. Perform reversals, voids, captures and credits by sending requests directly to the Network Online server. System Functionality With Web Services API, the communication between your system and Network Online gateway is encrypted providing security. The exchange of requests and responses occurs from server to server thus reducing the risks related to data transmission. Network Online Web Services supports transactions and various services including query, reversal, capture, void and credit. The feature is independent of programming language. 6

7 Overview You can send a query or perform reversal, void or capture for any of your transaction using the Web Service API. As a merchant, you can communicate with the Network Online server by sending query requests for particular transactions. Similarly, you can send requests for full authorization reversals, voids or captures for your transactions using the Web Service API. These requests contain certain parameters as defined in the document. Network Online processes the requests and sends an appropriate response with appropriate error message(s). Note: If you are required to process or store any sensitive card information, you need to comply with the PCI/DSS regulation. You can access the Web Service interface by using the Web Service Definition Language (WSDL) file. This will be provided by the Network Online. The WSDL file is an XML document that defines and describes the Web Services. For Web Service API, the file describes elements and classes related to requests, responses, queries and other parameters. 7

8 Getting Started with Web Service API Once you are onboarded as a merchant of Network online, you receive an . This provides the following: WSDL file/url to access the WSDL file Merchant ID Encryption Key When you are onboarded as a merchant, you must provide the IP address of your server through which the Web Service calls will be executed. The IP address gets registered and a check is conducted by the Network Online server for every request that you send. IMPORTANT Your IP address is the validation check for Network Online Web Services. You must execute the calls to the Web Services through the single IP address that you communicate to Network Online. If you connect to our server using a different IP address, the communication will be considered invalid. In case there is change in IP address then the same needs to be communicated. You can simply get started by creating classes with reference to the WSDL file, and use the Web Services for the various interactions with the Network Online system. Communicating with Network Online The steps listed below describe the communication between the merchant and Network Online using Web Service API: Y ou are required to encrypt the request by using the key and call the required Web Service operation. 2. Send the request to the Network Online Web Service API and wait for the response. 3. The Web Service API parses the request and triggers the call to the respective operation. 4. After processing the request, Network Online builds the response and sends it to your server IP from where the request originates. 5. You can access the response which could be a success or a failure response. The failure responses contain the error code and the error description. Procedure 1. Download the WSDL from the given URL. 2. Create all the classes that are required. This can be done with reference to the WSDL. 8

9 3. Invoke the method. For example, invokecapturews with two parameters MerchantID and NIOnline Ref ID. 4. This method will initiate the transaction for completing Capture with the Network Online. In return the method will return the parameters with success or failure as described in section. 9

10 Query API Overview Query Web Services API enables you to perform a query for your transactions. If you have not received a response for a particular transaction from Network Online, you can use Query API to confirm the final status of that transaction. Failure to complete a transaction may result due to various reasons. For example, if there is a network issue when the response is generated. Request fields IMPORTANT These fields come in three categories: Required (R): These are mandatory and must be passed to the API. Conditional (C): These fields may be required depending on the values in other fields, the specifics of which are defined in the comments column. Optional (O): These fields are not mandatory, but can result in improved fraud and risk monitoring, reporting and other analysis, if given. We suggest including all the fields listed above. Table 1 describes the Query API request fields: Note: The user input values highlighted in Bold are for emphasis ONLY. Table 1: Query API request fields Field name Description Ca t Comments Type / length 10

11 Field name Description Ca t MerchantID (R) MerchantOrder Number Unique merchant ID created at Network Online. Values other than the numeric Merchant ID allocated by Network Online to you will not be accepted. The order number of the transaction for which the query request is sent. (R) Comments Type / length (15) Note: If any value other than the Merchant ID assigned by Network Online is used or the MerchantID input is blank, no response will be sent. String (100) NIOnlineRefID Unique Reference ID that is generated at Network Online for a transaction. (O ) (16) TransactionTy pe Valid values: 01 for SALE 02 for AUTHROIZATION 03 for CAPTURE 04 for CREDIT 05 for VOID 06 for FULLAUTHREVERSAL (O ) String (2) Response Fields Table 2 describes the Query API Response fields: Table 2: Query API response fields Field name Description Category Type / length MerchantID The same value that is sent in the MerchantID (R) (15) field as described in the query request table. MerchantOrderNumber The same value that is sent in the MerchantOrderNumber field as described in the query request table. (R) String (100) 11

12 Field name Description Category Type / length NIOnlineRefID The same value that is sent in the NIOnlineRefID (C) (16) field as described in the query request table. If the query request is sent with the MerchantOrderNumber and without the NIOnlineRefID, the response provides the respective NIOnlineRefID except for validation failures where the ID is not provided. Currency The currency in which the transaction was booked. (C) String (3) Amount Status PayModeType The same value for which the transaction was booked. Status of the payment. In case of valid requests, the response is received with respect to the status of the transaction for which the request has been sent. If there is any error in the request, the failure response will be received with the respective error code and error message. The PayModeType used while booking the transaction is returned in this field for a valid query. Valid values: CC - Credit Card DC - Debit Card DD - Direct Debit (C) Decimal (14,2) (C) String (7) (C) String (2) 12

13 Field name Description Category Type / length CardType The CardType used while (C) String (20) booking the transaction is returned in this field for a valid query. Type of Card Valid values: MASTERCARD VISA DINERS AMEX JCB ErrorCode Response code for transaction status. If the query response is a failure, this represents the failure reason code. For a success response, the error code is Refer to the Error Codes section (R) String (5) ErrorResponseMess age TransactionType for values. This is a descriptive text message for the ErrorCode. The message for a success response is No Error. Refer to the Error Codes section for descriptions of each error code. The TransactionType used while booking the transaction is returned in this field for a valid query. Valid values: 01 for SALE 02 for AUTHROIZATION 03 for CAPTURE 04 for CREDIT 05 for VOID 06 for FULLAUTHREVERSAL In case an invalid value is entered while querying, the same value is returned, along with an error message and error code. (R) String (200) (C) String (2) 13

14 Field name Description Category Type / length CardEnrollmentResp This is the status of the (C) String (20) onse card used for the transaction. Valid values: Enrolled NotEnrolled This field is received for a valid query request. ECI_Values Electronic Commerce (C) String (3) Indicator (ECI) for the transaction Authentication. Valid values: 001: Fully Secure 002:Partially Secure 003:Unsecured This field is received for a valid query request. Please check the payment gateway Reason Codes for more details. FraudDecision Fraud manager decision (C) String (10) received for the transaction. Valid values: ACCEPT REJECT REVIEW The field is received as an empty field, unless the transaction was eligible for fraud management. FraudReason This is the reason due to which the Fraud Risk Management module declines the transaction. The field is received as an empty field, unless the transaction was eligible for fraud management. (C) String (400) 14

15 Field name Description Category Type / length DCC_Converted If the transaction is (C) String (3) converted as per Dynamic Currency Conversion (DCC). Valid values: YES NO The field is received as an empty field if DCC was applied on the transaction. DCC_ConvertedAmo unt The amount converted in the customer s domestic currency or the selected currency option. The field is received as an empty field if DCC was (C) (14,2) DCC_ConvertedCurr ency applied on the transaction. Currency code of the converted currency. The field is received as an empty field if DCC was applied on the transaction. (C) String (3) 15

16 Reversal/Capture API Overview The reversal API allows you to reverse a transaction at any stage of the order process. This could be from the stage prior to capture to from pre-settlement to post settlement. There are four types of reversals supported by Network Online: Full Authorization Reversals: You can use the full authorization reversal to release the hold on the credit card funds of the customer. This is done in order to reverse an authorization that is not captured. Merchants availing the authorize function can use this service. Void: You can use Void to cancel a request that has been submitted to the payment gateway. You can void a transaction only if the payment gateway has not submitted the credit request to Network Online. If this request has been sent from the payment gateway, then the void request is declined. It is possible to cancel a transaction that has been captured. However, you cannot undo a void request. Credit: You can use the credit service to credit the funds to the customer card after a transaction has been settled. You can use this function to avail a return policy on their goods and services. Capture: You can capture the authorization for an order that is fulfilled. Capturing the transaction ensures that the funds that were blocked on the customer card are debited. The merchant s bank account is credited on settlement. If you have partially fulfilled a customer s order, you must capture the authorization for the part of fulfilled order. In addition to Web Service API, it is possible to reverse transactions manually using the Network Online Merchant Console, as well as through a batch upload. As these modes of interaction do not require integration, they are not covered here. Refer to the functional specifications for more clarity on these functions. 16

17 Request and Response Fields Note: The user input values highlighted in Bold are for emphasis ONLY. Table 3 describes the full authorization reversal API request fields, which is invoked using <invokefullauthreversalws> method. Table 3: Full Authorization Reversal API request fields Field name Description Cat Comments Type/lengt h MerchantID Unique merchant ID provided by Network Online. Values other than the numeric Merchant ID allocated by Network Online to you will not be accepted. (R) (15) NIOnlineRefI D Unique Reference ID that is generated at Network Online for a transaction. (R) Note: If any value other than the Merchant ID assigned by Network Online is used or the MerchantID input is blank, no response will be sent. (16) Table 4 describes the full authorization reversal API response fields: Table 4: Full Authorization Reversal API response fields Field name Description Categor y MerchantID The same value that is sent in the (R) MerchantID field as described in the request table. Type/lengt h (15) NIOnlineRefID Currency The same value that is sent in the NIOnlineRefID field as described in the request table. The currency in which the transaction was booked. This field is received only for a valid full authorization reversal request. (R) (16) (C) String (3) Amount The amount for the transaction that (C) Decimal 17

18 Field name Description Categor y Type/lengt h is booked. (14,2) This field is received only for a valid full authorization reversal request. Status Status of the payment that is (R) String (7) received as: Success or Failure ErrorCode Response code for transaction (R) String (5) status. If the transaction fails, this represents the failure reason code. For a success response, the error code is Refer to the Error Codes section for values. ErrorMessage This is a descriptive text message for the ErrorCode. The message for a success response is No Error. Refer to the Error Codes section for descriptions of each error code. (R) String (200) BankReferenceNumb er The reference number generated by the payment gateway. This field is received only for a valid full authorization reversal request. (C) (22) Table 5 describes the Void API request fields using <invokevoidws>. Table 5: Void API request fields Field name Description Cat Comments Type/lengt h MerchantID Unique merchant ID provided by (R) Note: If any value Network Online. Values other than other than the (15) the numeric Merchant ID allocated by Merchant ID Network Online to you will not be assigned by accepted. Network Online is used or the MerchantID input is blank, no response will be sent. NIOnlineRefI D Unique Reference ID that is generated at Network Online for every transaction. (R) (16) 18

19 Table 6 Void API response fields: Table 6: Void API response fields Field name Description Categor y MerchantID The same value that is sent in the (R) MerchantID field as described in the request table. Type/lengt h (15) NIOnlineRefID Currency Amount Status ErrorCode ErrorMessage BankReferenceNumb er The same value that is sent in the NIOnlineRefID field as described in the request table. The currency in which the transaction was booked. This field is received only for a valid void request. The amount for the transaction that is booked. This field is received only for a valid void request. Status of the payment that is received as: Success or Failure Response code for transaction status. If the transaction fails, this represents the failure reason code. For a success response, the error code is Refer to the Error Codes section for values. This is a descriptive text message for the ErrorCode. The message for a success response is No Error. Refer to the Error Codes section for descriptions of each error code. The reference number generated by the payment gateway. This field is received only for a valid void request. (R) (16) (C) String (3) (C) Decimal (14,2) (R) String (7) (R) String (5) (R) (C) String (200) (22) 19

20 Table 7 describes the Capture API request fields <invokecapturews>. Table 7: Capture API request fields Field name Description Cat Comments Type/lengt h MerchantID Unique merchant ID provided by (R) Note: If any Network Online. Values other than value other than (15) the numeric Merchant ID allocated by the Merchant ID Network Online to you will not be assigned by accepted. Network Online is used or the MerchantID input is blank, no response will be sent. NIOnlineRefI D Unique Reference ID that is generated at Network Online for a transaction. Table 8 describes the Capture API response fields: (R) Table 8: Capture API response fields (16) Field name Description Categor y Type/lengt h MerchantID The same value that is sent in the MerchantID field as described in the (R) (15) request table. NIOnlineRefID The same value that is sent in the NIOnlineRefID field as described in (R) (16) the request table. Currency The currency in which the (C) String (3) transaction was booked. This field is received only for a valid capture request. Amount The amount for the transaction that is booked. (C) Decimal (14,2) This field is received only for a valid capture request. Status Status of the payment that is (R) String (7) received as: Success or Failure ErrorCode Response code for transaction status. If the transaction fails, this represents the failure reason code. (R) String (5) 20

21 Field name Description Categor y For a success response, the error code is Refer to the Error Codes section for values. ErrorMessage This is a descriptive text message (R) for the ErrorCode. The message for a success response is No Error. Refer to the Error Codes section for descriptions of each error code. BankReferenceNumb The reference number generated by (C) er the payment gateway. This field is received only for a valid capture request. Type/lengt h String (200) (22) Table 9 describes the Credit (Reversal) API request fields using the <invokecapturews>. Table 9: Credit (Reversal) API request fields Field name Description Cat Comments Type/lengt h MerchantID NIOnlineRefI D Unique merchant ID provided by Network Online. Values other than the numeric Merchant ID allocated by Network Online to you will not be accepted. Unique Reference ID that is generated at Network Online for a transaction. (R) (R) Note: If any value other than the Merchant ID assigned by Network Online is used or the MerchantID input is blank, no response will be sent. (15) (16) Amount Price for the item: Values up to 2 decimal places are allowed. For example, (R) Note: Amount is required only if you invoke the Reversals API. Decimal (14,2) Table 10 describes the Credit (Reversal) API response fields: Table 10: Credit (Reversal) API response fields Field name Description Categor y MerchantID The same value that is sent in the (R) MerchantID field described in the Type/lengt h (15) 21

22 Field name Description Categor y Type/lengt h request table. NIOnlineRefID The same value that is sent in the NIOnlineRefID field described in the (R) (16) request table. Currency The currency in which the (C) String (3) transaction was booked. This field is received only for a valid credit (reversal) request. Amount The amount for which the credit is requested for the transaction that is (R) Decimal (14,2) booked. Status Status of the payment that is (R) String (7) received as: Success or Failure ErrorCode Response code for transaction status. If the transaction fails, this represents the failure reason code. For a success response, the error code is Refer to the Error Codes section for values. (R) String (5) ErrorMessage RefundReferenceNu mber This is a descriptive text message for the ErrorCode. The message for a success response is No Error. Refer to the Error Codes section for descriptions of each error code. The Refund Reference Number generated by Network Online for successful credit transactions. (R) (C) String (200) (35) IMPORTANT SPECIAL CHARACTERS Following special characters are allowed in the request fields: _ (underscore). / (forward slash) (space), (comma) - (hyphen) : (colon) (Apostrophe) 22

23 HANDLING OF CASE SENSITIVITY In general, for any input field, if a value needs to be selected from a given list in the document, the values can be given in uppercase, camel case, mixed case or lower case format. These are converted into uppercase and stored in the system to maintain consistency while reporting. This is true for the fields TransactionMode, PaymodeType, CardType, TransactionSource, IsUserLoggedIn, and IgnoreValidationResult. Note: Response would not be received in the cases listed below: 1. No response received from PG. 2. Loss of server connection. 3. Session Time out 4. If any value other than the Merchant ID assigned by Network Online is used or the Merchant ID input is blank, no response will be sent. 23

24 Web Service Formats and Examples Each request and response message will be communicated in an encrypted format in a pipe separated string. To get started, you need to perform the Web Service call for the required operation. The response is received from the Network Online server. IMPORTANT The examples mentioned below are for demonstration purposes ONLY. When you use Web Service API, you will be assigned a Merchant ID and a respective key will be generated for the same. You must use the same Merchant ID and the key while using Web Services. Query Request Format Method Used: invokequeryws (MerchantID, OrderNo, NIOnlineRefID, TransactionType) Enter the information in the fields provided on the UI. Click Enter. This fields will be encrypted using AES 256 bit encryption and then sent to Network Online. MerchantID will not be encrypted in any request. Note: Even blank field should be encrypted String MerchantId = " "; String OrderNo = " " String NIOnlineRefID = " String TransactionType = 01" String enckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; EncDec aesencrypt1 = new EncDec(encKey); String OrderNo = aesencrypt1.encrypt(orderno); EncDec aesencrypt2 = new EncDec(encKey); String NIOnlineRefID = aesencrypt2.encrypt(nionlinerefid); EncDec aesencrypt3 = new EncDec(encKey); String TransactionType = aesencrypt3.encrypt(transactiontype); Where 01" indicates the Sale transaction type. The encrypted request is sent to the Network Online server using the invokequeryws (MerchantId, OrderNo, NIOnlineRefID, TransactionType) method. The response is explained below. 24

25 Query Response Format responseparameter = <Encrypted Message> The encrypted Message will be a pipe separated string of all fields in the same sequence given in the table. For example: String message = MerchantID + " " MerchantOrderNumber + " " + NIOnlineRefID + " " + Currency + " " + Amount + " " + Status + " " paymodetype + " " + cardtype +" " + ErrorCode + " " + ErrorMessage + " " + transtype + " " + cardenrollresponse + " " + ecivalues + " " + frauddecision + " " + fraudreason + " " + dccconverted + " " + dccamount + " " + dcccurrency + " "; This message will be encrypted using AES 256 bit encryption and sent to the response server. You can then decrypt the message and save the transaction status in your database. Code sample for Java programming language, applicable in JSP/Servlet: String deckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String encryptedmessage = request.getparameter("responseparameter"); // Decrypt the message using AES 256 bit decryption EncDec aesdecrypt = new EncDec(decKey, encryptedmessage); String message = aesdecrypt.decrypt(); At this point message should contain data similar to which is shown below. Success Response Example: MerchantID OrderNo NIOnlineRefID Currency Amount Status PayModeType CardType ErrorCod e ErrorMessage TransType cardenrollresponse ecivalues frauddecision fraudreason dccconverted dccamount dcccurrency AED 11.0 Capture/Sale Success CC Visa No Error. Enrolled Partially Secure Yes USD Failure Response Example: MerchantID OrderNo NIOnlineRefID Status ErrorCode ErrorMessage TransType Failure Technical Error 01 Full Auth Reversals API Request Format Method Used: invokefullauthreversalws(merchantid, NiOnlineRefID) Enter the information in the fields provided on the UI. Click Enter. This fields will be encrypted using AES 256 bit encryption and then sent to Network Online. MerchantID will not be encrypted in any request. Note: Even blank field should be encrypted 25

26 String MerchantId = " "; String NIOnlineRefID = " String enckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; EncDec aesencrypt = new EncDec(encKey); String NIOnlineRefID = aesencrypt.encrypt(nionlinerefid); Send this requestparameter by using the invokefullauthreversalws (MerchantID, NIOnlineRefID) method to the Network Online server and wait for the response. Full Auth Reversals API Response Format responseparameter = <Encrypted Message> Here Encrypted Message will be a pipe separated string of all fields in the same sequence given in the table. For example: String message = MerchantID + " " + NIOnlineRefID + " " + Currency + " " + Amount + " " + Status + " " + ErrorCode + " " + ErrorMessage + " " + BankReferenceNumber + " "; This message will be encrypted using AES 256 bit encryption and sent to the merchant server. You can decrypt the message and save the transaction status in their database. Code sample for Java programming language, applicable in JSP/Servlet: String deckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String encryptedmessage = request.getparameter("responseparameter"); // Decrypt the message using AES 256 bit decryption EncDec aesdecrypt = new EncDec(decKey, encryptedmessage); String message = aesdecrypt.decrypt(); At this point message should contain data similar to which is shown below. Success Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMessage BankReferenceNumber AED SUCCESS No Error Failure Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMessage FAILURE Invalid Transaction Reference ID. Similarly you use Web Services for the following operations as described below and receive the respective responses: This fields will be encrypted using AES 256 bit encryption and then sent to Network Online. MerchantID will not be encrypted in any request. Note: Even blank field should be encrypted 26

27 1. Transaction Type: Capture Method: invokecapturews (MerchantID, NIOnlineRefID) String enckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String NIOnlineRefID = " EncDec aesencrypt = new EncDec(encKey); String NIOnlineRefID = aesencrypt.encrypt(nionlinerefid); Request: InvokeCaptureWS ( , NIOnlineRefID) Success Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMe ssage BankReferenceNumber AED SUCCESS No Error Failure Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMe ssage FAILURE Invalid Transaction Reference ID. 2. Transaction Type: Credit (Reversal) Method: invokereversalws (MerchantID, NIOnlineRefID, Amount) String enckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String NIOnlineRefID = " String Amount = "10 EncDec aesencrypt1 = new EncDec(encKey); String NIOnlineRefID = aesencrypt1.encrypt(nionlinerefid); EncDec aesencrypt2 = new EncDec(encKey); String Amount = aesencrypt2.encrypt(amount); Request: InvokeReversalWS ( , NIOnlineRefID, Amount) Success Response Example: MerchantID NIOnlineRefID Currency Amount Available Amount Status ErrorCode ErrorMessage RefundReferenceNumber AED SUCCESS No Error Failure Response Example: MerchantID NIOnlineRefID Currency Amount Available Amount Status ErrorCode ErrorMessage FAILURE Refund amount greater than transaction amount. 3. Transaction Type: Void Method: invokevoidws (MerchantID, NIOnlineRefID) String enckey = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String NIOnlineRefID = "

28 EncDec aesencrypt = new EncDec(encKey); String NIOnlineRefID = aesencrypt.encrypt(nionlinerefid); Request: InvokeVoidWS ( , NIOnlineRefID) Success Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMe ssage BankReferenceNumber AED SUCCESS No Error Failure Response Example: MerchantID NIOnlineRefID Currency Amount Status ErrorCode ErrorMe ssage FAILURE Invalid Transaction Reference ID. Encryption and Authentication Test Merchant Encryption / Decryption Key [KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84=] Production Merchant Encryption / Decryption Key [Will be provided when the integration is complete and live MID is created] Encryption / Decryption We use AES 256 bit encryption to ensure secure message transmission. Pre-requisites: Java 6 (1.6) JCE (Java Cryptography Extension) library [To be provided as part of Merchant Integration Kit] NI Encryption / Decryption library [To be provided as part of Merchant Integration Kit] Apache Commons Codec library [To be provided as part of Merchant Integration Kit] Encryption / Decryption Key [For test environment, use the key given below. And for production environment, you will get a separate key.] The.jar files will be provided depending on the platform that is used. Setup Steps: 1. Copy EncDec.jar and commons-codec-1.8.jar files from lib folder into the classpath. 2. Take backup and replace local_policy.jar and US_export_policy.jar files in jre/lib/security folder of your installed JRE. Please refer to README.txt file in jce folder for detailed description. How to use encryption or decryption Please refer to the sample java code given below: package com.sample; import com.ni.ecom.util.encdec; public class TestEncDec { public static void main(string[] args) { String key = "KtKU+n34+ml3ErXW9+ioPw/ypPiUuce1wunTnAv8e84="; String str = " AED Internet CC xxxxxxxxxxxxxxxxxx xxx Visa 28

29 } Soloman Vandy Abhinav Nagar Borivali Mumbai Maharashtra IN 1 Book aaa bbb ccc ddd eeee "; EncDec aesencrypt = new EncDec(key); String encryptedstr = aesencrypt.encrypt(str); System.out.println("Encrypted String: " + encryptedstr); EncDec aesdecrypt = new EncDec(key, encryptedstr); String decryptedstr = aesdecrypt.decrypt(); System.out.println("Decrypted String: " + decryptedstr); } 29

30 Error Codes If there is any error in the inputs or in the processing of the inputs given by the merchant, the application returns an error code. These can be classified as follows: NeO Error Codes The Network Online errors result due to invalid user inputs as indicated in Table 11. Table 11: NeO Error Codes Field Name/Error Type Error Code Error Description MerchantID Invalid Merchant ID Merchant Transaction Invalid Referral URL Referrer URL Amount Invalid Amount ExpiryMonth Invalid Expiry Month ExpiryYear Invalid Expiry Year Amount Refund amount greater than transaction amount. MerchantOrderNumber, CurrencyCode, Amount, TransactionType, Transaction Mode, CreditCardNumber, CVV, ExpiryYear, ExpiryMonth, CardType, PayModeType The request is missing one or more required fields. TransactionSource, ProductInfo, IsUserLoggedIn, ItemTotal, ItemCategory, udf1, udf2, udf3, udf4, udf One or more fields in the request contain invalid data. NIOnlineRefID Invalid Transaction Reference ID Merchant Status Merchant is inactive. Validity Merchant is not in valid period. MerchantOrderNumber Invalid Merchant Order Number Currency Invalid Currency 30

31 Field Name/Error Type Error Code Error Description Currency Currency not mapped to the merchant. Transaction Slab Transaction amount is greater than transaction defined slab. ResponseURL Please provide a valid response URL. TransactionType Invalid Transaction Type TransactionMode Invalid Transaction Mode PayModeType Invalid Paymode Type CreditCardNumber Invalid Credit or Debit Card Number CVV Invalid Card Verification Value CardType Invalid Card Type TransactionSource Invalid Transaction Source IsUserLoggedIn Invalid user logged in value Capture Date Invalid Capture Date Transaction Request Error while decrypting transaction request. Encryption System Mapping One or more system mapping is missing. Customer IP Address Invalid IP address. Transaction Not Permitted. Encryption Key Security Key Not Found. Refund Only Partial Refund or Settled Transactions can be Reversed. Transaction Type Only Capture and Credit transactions can be Voided. Transaction Type Only Authorization Transactions can be Reversed. Refund Balance Amount Insufficient funds in merchant account to process refunds. No Records Found No Records Found Any RunTime Technical Exceptions * e.g. - Null Pointer Exceptions - DB Failure Exceptions - Exceptions due to Parameters Mismanagement Technical Error * Please note for error code received, please contact merchant support helpdesk. 31

32 Payment Gateway Error Codes Payment Gateway error codes received are transaction related, as indicated in Table 12. Table 12: Payment Gateway Error Codes Field Name/Error Type Error Code Error Description Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file. General Card Credential Error General decline of the card. No other information was provided by the issuing General Card Credential Error bank. General Card Credential Error Insufficient funds in the account. General Card Credential Error Stolen or lost card General Card Credential Error Issuing bank unavailable. General Card Credential Error Inactive card or card not authorized for card-not-present transactions. General Card Credential Error American Express Card Identification Digits (CID) did not match. General Card Credential Error The card has reached the credit limit. General Card Credential Error Invalid CVN General Card Credential Error Invalid account number General Card Credential Error The card type is not accepted by the payment processor The requested capture amount exceeds the originally authorized amount. Capture Amount General Card Credential Error General decline by the processor The authorization has already been reversed The authorization has already been captured The requested transaction amount must match the previous transaction amount You requested a capture, but there is no corresponding, unused authorization record The order is rejected by FRM Module The transaction has already been settled or reversed The customer cannot be authenticated Server Timeout The request was received but there was a server timeout. This error does not include timeouts between the client and the server. 32

33 Field Name/Error Type Error Code Error Description The issuing bank has questions about the request The customer matched an entry on the processor s negative file The capture or credit is not voidable because the capture or credit information has already been submitted to your processor You requested a credit for a capture that was previously voided Stand-alone credits are not allowed. Invalid Request * Request data posted is invalid * Please note for error code received, please contact merchant support helpdesk. 33