We are very excited to welcome contributors, if you have worked on any gateway you can implement that gateway in our library and support the open source world.<\/p>\n
You can find our github repository here<\/a><\/p>\n Before you begin to implement a gateway there are some other classes you should see first.<\/p>\n Below are the classes defined briefly.<\/p>\n The main thing when working with gateways you post some data to gateway and parse the response.<\/p>\n To work with http post request this class provides two overloaded static httpPost methods.<\/p>\n So you don\u2019t have to worry about handling http requests.<\/p>\n While you are working with multiple gateways the main problem developer usually face is some gateways receive xml while some receive JSON or query string since J2pay always returns JSON Response so you do not have to worry about data conversion from between any of these xml, JSON or query string.<\/p>\n Here is the list of helper classes located in com.tranxactive.paymentprocessor.net package.<\/p>\n Note: All of the methods defined in helper classes are static.<\/p>\n To provide generic response j2pay provides five response classes located in com.tranxactive.paymentprocessor.gateways.responses package.<\/p>\n As you can identify by their names if you are working with purchase method you will be using PurchaseResponse class if working with rebill method you will be using RebillRespons class and so on<\/p>\n ErrorResponse class is the only class which will be used in all four methods.<\/p>\n One thing you should also know four classes except ErrorResponse considered as success response. So we will be returning them if and only if transaction was successful.<\/p>\n ParamList is an enum located in com.tranxactive.paymentprocessor.gateways.parameters package contains the list of variables that must be keep generic in all transactions like if you would like to assign transaction id to variable transactionId there are some chances of typo, but if you will be using paramList enum you are very safe.<\/p>\n Here is how could you use that while assigning transactionId In JSON.<\/p>\n Now you have all the knowledge required to integrate a new gateway. In this example we will be integrating NMI gateway.<\/p>\n While working on this example we assumed you have read the NMI official documentation.<\/p>\n To integrate NMI gateway we will create a class in com.tranxactive.paymentprocessor.gateways package with the name NMIGateway.<\/p>\n Next we will extends the Gateway class which lead us to implementing all the methods that must be present in a gateway.<\/p>\n Here is how our class will look like.<\/p>\n Next we will add four below methods at the end of our class. These will be helping us to build the final parameters that need to be posted on the gateway.<\/p>\n Next we will define apiURL variable globally where all request will be posted. Next we will work on four SampleParameters methods.<\/p>\n First and most important is getApiSampleParameters method which is required to perform all transactions.<\/p>\n If you have read the NMI documentation you will see API parameters are username and password.<\/p>\n Here is how getApiSampleParameters method will look like.<\/p>\n Below are the three remaining methods after updating.<\/p>\n Next we will be working on four buildparameters methods. Here is how these look like after inserting our code.<\/p>\n Next we will be working on purchase method.<\/p>\n First of all we will build our final parameters that need to be posted on gateway with the help of buildPurchaseParameters method.<\/p>\n Next we will define some variables to handle the request don\u2019t worry it\u2019s all depends on how you code.<\/p>\n Since NMI requires queryString data to be posted so we are using two helper class.<\/p>\n JSONHelper<\/b> and\u00a0QueryStringHelper<\/b><\/p>\n First we will urlencode the json returned by buildPurchaseParameters with the help of this code.<\/p>\n Next we converted the encoded json to query string with the help of this code.<\/p>\n You must be wondering why we initialized errorResponse but set successResponse as null. That all for some programming login to handle the request easily.<\/p>\n Next we will be posting the data to gateway, here is how we will do that.<\/p>\n Here are two scenarios that must keep in mind.<\/p>\n Here is how you will handle second scenario.<\/p>\n If the communication with gateway server was successful then our code will not return from this point and continue.<\/p>\n Next we will get the gateway response and parse it to JSON so we can easily work on response.<\/p>\n As you can see we again used the QueryStringHelper and JSONHelper. Wasn\u2019t that easy with the help of helper class.<\/p>\n As we know if gateway response was successful than it must return response code 100. See below code.<\/p>\n Let\u2019s understand the above code line by line.<\/p>\n httpResponse by default set the success to false, so we are only setting it to true in success case as we did above.<\/p>\n We initialized successResponse variable defined in the beginning of method.<\/p>\n When you take a look at the code of PurchaseResponse class you will see all the parameters that must be set before returning the response.<\/p>\n Next we set the amount and currency that was charged.<\/p>\n Since it\u2019s our responsibility to provide the ready to use parameters required for rebill, refund or void.<\/p>\n Here is how we did this.<\/p>\n But what if response what not success and we got some error like insufficient fund or avs error.<\/p>\n Here is how we did this in else block.<\/p>\n Next we will return the final response that will be HTTPResponse.<\/p>\n That\u2019s all we have successfully integrated the NMI purchase method, next three methods will be same except you will be using different Response classes for each of them i.e. you will be using<\/p>\n RebillResponse in rebill method. It is highly recommended to see source of all the these response class and also sample responses (given here)<\/p>\n To see the complete code of NMI gateway you can see on our github repository<\/a>.<\/p>\nHTTPClient<\/h2>\n
\n
Helpers<\/h2>\n
\n
Responses<\/h2>\n
\n
ParamList<\/h2>\n
JSONObject json = new JSONObject();\n Json.put(ParamList.TRANSACTION_ID.getName(), \"1234567890\");<\/pre>\n
Example<\/h2>\n
Let\u2019s code.<\/h2>\n
public class NMIGateway extends Gateway{\n\n @Override\n public HTTPResponse purchase(JSONObject apiParameters, Customer customer, CustomerCard customerCard, Currency currency, float amount) { }\n\n @Override\n public HTTPResponse refund(JSONObject apiParameters, JSONObject refundParameters, float amount) { }\n\n @Override\n public HTTPResponse rebill(JSONObject apiParameters, JSONObject rebillParameters, float amount) { }\n\n @Override\n public HTTPResponse voidTransaction(JSONObject apiParameters, JSONObject voidParameters) { }\n\n @Override\n public JSONObject getApiSampleParameters() { }\n\n @Override\n public JSONObject getRefundSampleParameters() { }\n\n @Override\n public JSONObject getRebillSampleParameters() { }\n\n @Override\n public JSONObject getVoidSampleParameters() { }\n }<\/pre>\nprivate JSONObject buildPurchaseParameters(JSONObject apiParameters, Customer customer, CustomerCard customerCard, Currency currency, float amount){}\n private JSONObject buildVoidParameters(JSONObject apiParameters, JSONObject voidParameters) {}\n private JSONObject buildRefundParameters(JSONObject apiParameters, JSONObject refundParameters, float amount){}\n private JSONObject buildRebillParameters(JSONObject apiParameters, JSONObject rebillParameters, float amount){}<\/pre>\nprivate final String apiURL = \"https:\/\/secure.networkmerchants.com\/api\/transact.php\";<\/pre>\n
@Override\n public JSONObject getApiSampleParameters() {\n return new JSONObject()\n .put(\"username\", \"the api user name use demo as the user name for testing\")\n .put(\"password\", \"the api password use password as the password for testing\");\n }<\/pre>\n@Override\n public JSONObject getRefundSampleParameters() {\n return new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), \"the transaction id which will be refunded\");\n }\n\n @Override\n public JSONObject getRebillSampleParameters() {\n return new JSONObject()\n .put(\"customerVaultId\", \"the customer vault id\");\n }\n\n @Override\n public JSONObject getVoidSampleParameters() {\n return new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), \"the transaction id which will be void\");\n }<\/pre>\nprivate JSONObject buildPurchaseParameters(JSONObject apiParameters, Customer customer, CustomerCard customerCard, Currency currency, float amount) {\n\n JSONObject object = new JSONObject();\n object\n .put(\"type\", \"sale\")\n .put(\"username\", apiParameters.getString(\"username\"))\n .put(\"password\", apiParameters.getString(\"password\"))\n .put(\"ccnumber\", customerCard.getNumber())\n .put(\"ccexp\", customerCard.getExpiryMonth() + customerCard.getExpiryYear().substring(2))\n .put(\"cvv\", customerCard.getCvv())\n .put(\"amount\", amount)\n .put(\"currency\", currency)\n .put(\"first_name\", customer.getFirstName())\n .put(\"last_name\", customer.getLastName())\n .put(\"address1\", customer.getAddress())\n .put(\"city\", customer.getCity())\n .put(\"state\", customer.getState())\n .put(\"zip\", customer.getZip())\n .put(\"country\", customer.getCountry().getCodeISO2())\n .put(\"phone\", customer.getPhoneNumber())\n .put(\"email\", customer.getEmail())\n .put(\"ipaddress\", customer.getIp())\n .put(\"customer_vault\", \"add_customer\");\n\n return object;\n\n }\n\n private JSONObject buildVoidParameters(JSONObject apiParameters, JSONObject voidParameters) {\n\n JSONObject object = new JSONObject();\n object\n .put(\"type\", \"void\")\n .put(\"username\", apiParameters.getString(\"username\"))\n .put(\"password\", apiParameters.getString(\"password\"))\n .put(\"transactionid\", voidParameters.getString(ParamList.TRANSACTION_ID.getName()));\n\n return object;\n }\n\n private JSONObject buildRefundParameters(JSONObject apiParameters, JSONObject refundParameters, float amount) {\n\n JSONObject object = new JSONObject();\n object\n .put(\"type\", \"refund\")\n .put(\"username\", apiParameters.getString(\"username\"))\n .put(\"password\", apiParameters.getString(\"password\"))\n .put(\"transactionid\", refundParameters.getString(ParamList.TRANSACTION_ID.getName()))\n .put(\"amount\", Float.toString(amount));\n\n return object;\n }\n\n private JSONObject buildRebillParameters(JSONObject apiParameters, JSONObject rebillParameters, float amount) {\n\n JSONObject object = new JSONObject();\n object\n .put(\"username\", apiParameters.getString(\"username\"))\n .put(\"password\", apiParameters.getString(\"password\"))\n .put(\"customer_vault_id\", rebillParameters.getString(\"customerVaultId\"))\n .put(\"amount\", Float.toString(amount));\n\n return object;\n }<\/pre>\nJSONObject requestObject = this.buildPurchaseParameters(apiParameters, customer, customerCard, currency, amount);<\/pre>\n
JSONObject responseObject;\n String requestString;\n String responseString;\n int responseCode;\n requestObject = JSONHelper.encode(requestObject);\n requestString = QueryStringHelper.toQueryString(requestObject);\n HTTPResponse httpResponse;\n\n PurchaseResponse successResponse = null;\n ErrorResponse errorResponse = new ErrorResponse();<\/pre>\n
requestObject = JSONHelper.encode(requestObject);<\/pre>\n
requestString = QueryStringHelper.toQueryString(requestObject);<\/pre>\n
httpResponse = HTTPClient.httpPost(this.apiURL, requestString, ContentType.APPLICATION_FORM_URLENCODED);<\/pre>\n
\n
if (httpResponse.getStatusCode() == -1) {\n return httpResponse;\n }<\/pre>\nresponseString = httpResponse.getContent();\n responseObject = JSONHelper.decode(QueryStringHelper.toJson(responseString));\n responseCode = responseObject.getInt(\"response_code\");<\/pre>\n
if (responseCode == 100) {\n httpResponse.setSuccessful(true);\n successResponse = new PurchaseResponse();\n successResponse.setMessage(responseObject.getString(\"responsetext\"));\n successResponse.setTransactionId(responseObject.get(\"transactionid\").toString());\n successResponse.setCardValuesFrom(customerCard);\n successResponse.setAmount(amount);\n successResponse.setCurrencyCode(currency);\n\n successResponse.setRebillParams(new JSONObject()\n .put(\"customerVaultId\", responseObject.get(\"customer_vault_id\").toString())\n );\n\n successResponse.setRefundParams(new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), responseObject.get(\"transactionid\").toString())\n );\n\n successResponse.setVoidParams(new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), responseObject.get(\"transactionid\").toString())\n );\n\n } else {\n errorResponse.setMessage(responseObject.getString(\"responsetext\"));\n }<\/pre>\nhttpResponse.setSuccessful(true);<\/pre>\n
successResponse = new PurchaseResponse();<\/pre>\n
\/\/this sets the gateway success message.\n successResponse.setMessage(responseObject.getString(\"responsetext\"));<\/pre>\n
\/\/this sets the gateway returned transaction id.\n successResponse.setTransactionId(responseObject.get(\"transactionid\").toString());<\/pre>\n
\/\/this is our standard we provide some card detail in purchase response. You will see in final response.\n successResponse.setCardValuesFrom(customerCard);<\/pre>\n
successResponse.setAmount(amount);\n successResponse.setCurrencyCode(currency);<\/pre>\n
successResponse.setRebillParams(new JSONObject()\n .put(\"customerVaultId\", responseObject.get(\"customer_vault_id\").toString())\n );\n\n successResponse.setRefundParams(new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), responseObject.get(\"transactionid\").toString())\n );\n\n successResponse.setVoidParams(new JSONObject()\n .put(ParamList.TRANSACTION_ID.getName(), responseObject.get(\"transactionid\").toString())\n );<\/pre>\n
errorResponse.setMessage(responseObject.getString(\"responsetext\"));<\/pre>\n
if (successResponse != null) {\n successResponse.setGatewayResponse(responseObject);\n httpResponse.setContent(successResponse.getResponse().toString());\n } else {\n errorResponse.setGatewayResponse(responseObject);\n httpResponse.setContent(errorResponse.getResponse().toString());\n }\n\n return httpResponse;<\/pre>\n
\nRefundResponse in refund method.
\nVoidResponse in voidTransaction method.
\nInstead of PurchaseResponse.<\/p>\n