Merchant Integration Guide



1. Overview

This document provides NoqoodyPay specification including integration with merchant website, and specification of initializing payment process. This document also provides HTTP API used to get payment token, validating payment request, as well as payment response with HTTP API specification.

2. Authentication and Security

Noqoody payment gateway exchanges data between merchant and gateway in the form of Request and Response.

All communications with NoqoodyPay are encrypted with an external layer of encryption “SSL” Once you are enrolled in the NoqoodyPay, you will be provided with a unique UserID for both a sandbox and a production environment. The NoqoodyPay environment UserID will be provided upon successful completion of your sandbox integration. Please note that the UserID is not interchangeable. It is merchant’s responsibility to keep the credentials in a secure and hidden environment.

3. Merchant Authorization

Noqoodypay require user identification for each transaction level authentication and authorization.

4. API Request Format

Request should be made in POST / GET methods unless otherwise stated for the given API request. Response data will be provided in JSON format.

Additionally, we have developed a testing environment to simplify integration process.

To access the testing environment please go to the following URL: http://sandbox.noqoodypay.com

4.1 Integration of Payment Gateway via Noqoody Widget

NoqoodyPay will provide a widget which a merchant can insert into the checkout page.

<script type="text/javascript"
src="//sandbox.noqoodypay.com/api/api/WebPayment/GetWe
bJsApi/{your_project_code}"></script>

Your project code will be provided by NoqoodyPay Admin. Please note that this script can only be loaded via a specific “Access URL”. Merchant has to provide that URL. Access URL is domain from where you will be loading the Payment Widget.

Once the widget is loaded successfully you must provide the following parameters to initialize the payment widget.

Initializing the widget is done through Javascript. A sample code is mentioned below.

<!DOCTYPE html>
<html>
<head>
<title>Checkout Page</title>
</head>
<body>
Your HTML code goes here
<div id=”'mybutton'”></div>
</body>
</html>
<script type="text/javascript">
var d = new Date();
 var n = d.getTime();
 var dx=Math.floor((Math.random() * 1000) + 1);
 var TransactionAmount=(item.DefaultDenomination.Price).toFixed(2); //Your
Billing Amount
 var MobileAmount = ""; //Your Billing Amount
 var Description= item.DefaultDenomination.Denomination; //Your Product detail
less than 40 characters
var TransactionReference= result.TransactionReference;//"Ref" + n + "QP" + dx;
//Your Transaction Reference Number should be unique for every Request
 qpay.SetPayButton('mybutton');// Pass the element ID of the Button to place your
widget on your checkout page.
 // qpay.Init(TransactionAmount,Description,TransactionReference,MobileAmount);
 qpay.Init(TransactionAmount,Description,TransactionReference,MobileAmount,
{CustomerMobile},{CustomerEmail},{CustomerName},{Gender },{QID};
</script>

Please note that while initializing the NoqoodyPay widget all parameters are mandatory except Gender and QID. You can insert ‘NA’ in these parameters if you don’t have data available.

Once the widget is loaded it will be displayed on your checkout page


All your payment methods will be displayed. Once you click the payment method, the browser will be redirected to the payment page, where the user will fill the required information to complete the payment process.

Once the payment is completed, the browser will be redirected to the URL provided by the merchant. That URL contains the payment response. Response will be in a query string format.

https://{your_Response_url} ?success=True&code=OK&messag
e=Payment processed
successfully.&InvoiceNo={invoce_number}
&reference={your_transaction_reference_number}
&PUN={private_unique_number}

Merchant must get the parameters sent from NoqoodyPay to merchant response URL.

After getting the response, Merchant must validate the payment. To validate the API, merchant has to send the GET request and the response data will be in a JSON response

https://sandbox.noqoodypay.com/api/api/Members/GetTra
nsactionDetailStatusByClientReference/?ReferenceNo={y
our_unique_reference_number_that_you_received_on_your
_response_url}

Please note that in the validation request, merchant must add access_token in the request header.

Request Header key will be “Authorization” and its value will be “bearer {access_token}”

To get the access token, merchant must call an API, it will be a POST request

https://sandbox.noqoodypay.com/api/token

Content Type of the request will be “application/x-www-formURLencoded”

Parameters will be

“grant_type=password&username={NoqoodyPayUserName}&pa
ssword={NoqoodypayPassword}”

Merchant will receive a JSON response

{
 "access_token": "FtmYG7Qb4Z5ZjjqTu7GoVJapvNaD7AzYBofCWNMYGLNI_iKc0k0aIQUhyJm12wMOGckLtl6wPx7Eg08--
J0_M3Qcxbh5bliasdasdsklBSjx3xkGaQhgyEiTkn5TVc3_DMmdNmVZR9bdxEalzm0FfpHxpvgZUwpN0lEIDvz
L_RF5cq0_ABmjRdN99-b7WLEjhtf4kaE3gyTRDJybvLAkGyIQGuzItjjbyAyjHdXgkfH1pUJ6_gwupcI1FGJUinqeuvFdpPlFkeoueciPChJXc6oo9eJ2qlZxHBi0f2oEyZ60dCtwITqQmO5r8iw5SjcEctnbJG2Uuk6BNAmoMZNKD6mBZ9HeR3Bltm9YH
WMIybiiJx6qldzGSHtxVhVA9SDhC9_6ZLToGqMtBqtKMlzOSIsubIgWQCLQJZAH-cx9Lnea53QPTDEsvO_f-kvckOKYqOaAbkqro_WCGFZgFcOr5ze2nN-rar1WVTlNvb215k2SSEiCWcUjTZ8riOS1gNSW3_jHRMoyIolHKycy6JZkPMYXwhDEaRlouUch63sH8AOaIXu9l9r10ZcLnnZGLwvmodzAxaMsqAi30Kxr7hw0MKOs5Q7q9uKSYxPeT0",
 "token_type": "bearer",
 "expires_in": 1209599,
 "userName": "your_user_namr",
 "Name": "merchant_name",
 "Role": "NoqoodayPay User",
 "ImageLocation": "your_logo_location",
 "Email": "merchant_email",
 ".issued": "Sat, 19 Jan 2019 08:59:12 GMT",
 ".expires": "Sat, 02 Feb 2019 08:59:12 GMT"
}

Merchant will use access_token from this response to validate the payment as mentioned earlier.

To validate the payment, merchant must call a validation API, a GET request and response data will be in a JSON response.

https://sandbox.noqoodypay.com/api/api/Members/GetTra
nsactionDetailStatusByClientReference/?ReferenceNo={y
our_unique_reference_number_that_you_received_on_your
_response_url}

In the request header merchant must pass the following parameters.

Request Header key will be “Authorization” and its value will be “bearer {access_token_received_from_token_api}”

A JSON response will be returned containing the payment validation result.

{
 "TransactionID": "3242322386",
 "ResponseCode": "Success 1",
 "Amount": 95,
 "TransactionDate": "2018-11-14T18:03:52.927",
 "TransactionStatus": "9",
 "Reference": "your_unique_reference",
 "ServiceName": "payment_method(paypal,creditcard,debitcard,qpaymobile)",
 "Mobile": "974xxxxxxxx",
 "TransactionMessage": "Success 1",
 "PUN": "private_unique_number",
 "description": "your_tansaction_description",
 "InvoiceNo": "noqoody_invoice_no",
 "DollarAmount": 0,
 "Email": null,
 "PayeeName": null,
 "success": true,
 "code": "OK",
 "message": "Transaction Found",
 "errors": []
}

Please note if “success=true”, the payment was collected successfully.

This will complete the transaction process.

4.2 Integration of Payment Gateway via API

Merchants who don’t want to use NoqoodyPay widget can use this integration method. This method is also very simple and easy to integrate.

Firstly, merchant must get the access_token

To get the access token, merchant must call an API, it will be a POST request
https://sandbox.noqoodypay.com/api/token

Content Type of the request will be “application/x-www-formURLencoded” Parameters will be

“grant_type=password&username={NoqoodyPayUserName}&pa
ssword={NoqoodypayPassword}”

Merchant will receive a JSON response

{
 "access_token": "FtmYG7Qb4Z5ZjjqTu7GoVJapvNaD7AzYBofCWNMYGLNI_iKc0k0aIQUhyJm12wMOGckLtl6wPx7Eg08--J0_M3Qcxbh5bliasdasdsklBSjx3xkGaQhgyEiTkn5TVc3_DMmdNmVZR9bdxEalzm0FfpHxpvgZUwpN0lEIDvz
L_RF5cq0_ABmjRdN99-b7WLEjhtf4kaE3gyTRDJybvLAkGyIQGuzItjjbyAyjHdXgkfH1pUJ6_gwupcI1FGJUinqeuvFdpPlFkeoueciPChJXc6oo9eJ2qlZxHBi0f2oEyZ60dCtwITqQmO5r8iw5SjcEctnbJG2Uuk6BNAmoMZNKD6mBZ9HeR3Bltm9YH
WMIybiiJx6qldzGSHtxVhVA9SDhC9_6ZLToGqMtBqtKMlzOSIsubIgWQCLQJZAH-cx9Lnea53QPTDEsvO_fkvckOKYqOaAbkqro_WCGFZgFcOr5ze2nN-rar1WVTlNvb215k2SSEiCWcUjTZ8riOS1gNSW3_jHRMoyIolHKycy6JZkPMYXwhDEaRlouUch63sH8AOaIXu9l9r10ZcLnnZGLwvmodzAxaMsqAi30Kxr7hw0MKOs5Q7q9uKSYxPeT0",
 "token_type": "bearer",
 "expires_in": 1209599,
 "userName": "your_user_namr",
 "Name": "merchant_name",
 "Role": "NoqoodayPay User",
 "ImageLocation": "your_logo_location",
 "Email": "merchant_email",
 ".issued": "Sat, 19 Jan 2019 08:59:12 GMT",
 ".expires": "Sat, 02 Feb 2019 08:59:12 GMT"
}

Merchant will use access_token from this to get the payment links.

To GET the payment Links, merchant must call PaymentURL API, a GET request and response data will be a JSON response.

https://sandbox.noqoodypay.com/api/api/Members/
GetPaymentLinks/{your_project_code_provided_by_noqood
y_admin}? reference={your_unique_reference_no}
&description={your_payment_description_less_than_40_c
hars}
&amount={payment_amount}&CustomerEmail={customer_emai
l}&CustomerMobile={customer+mobile}&CustomerName={cus
tomer_name}

In the request header merchant must pass the following parameters.

Request Header key will be “Authorization” and its value will be “bearer {access_token_received_from_token_api}”

A JSON response will be returned containing the payment URL result.

Please note if “success=true”, the payment URL was successfully generated

{"PaypalLink":"http_paypal_payment_url","NapsLink":"http_na
ps_payment_link","CreditCardLink":"http_credit_card_link","M
obileLink":"http_mobile_payment_link","CyberSecureLink":"htt
p_credit_card_payment_link","success":true,"code":"OK","mes
sage":"","errors":[]}

Merchant can use these payment links in browser and the payment process will start.

Once the payment is completed, the browser will be redirected to the URL provided by the merchant. That URL contains the payment response. Response will be in a query string format.

https://{your_Response_url} ?success=True&code=OK&messag
e=Payment processed successfully.&InvoiceNo={invoce_number}
&reference={your_transaction_reference_number}
&PUN={private_unique_number}

Merchant must get the parameters sent from NoqoodyPay to merchant response URL.

After getting the response, Merchant must validate the payment. To validate the API merchant must send the GET request and response data will be in a JSON response.

https://sandbox.noqoodypay.com/api/api/Members/GetTra
nsactionDetailStatusByClientReference/?ReferenceNo={y
our_unique_reference_number_that_you_received_on_your
_response_url}

Please note that in the validation request, merchant must add access_token in the request header as mentioned earlier

A JSON response will be returned containing the payment validation result.

{
 "TransactionID": "3242322386",
 "ResponseCode": "Success 1",
 "Amount": 95,
 "TransactionDate": "2018-11-14T18:03:52.927",
 "TransactionStatus": "9",
 "Reference": "your_unique_reference",
 "ServiceName": "payment_method(paypal,creditcard,debitcard,qpaymobile)",
 "Mobile": "974xxxxxxxx",
 "TransactionMessage": "Success 1",
 "PUN": "private_unique_number",
 "description": "your_tansaction_description",
 "InvoiceNo": "noqoody_invoice_no",
 "DollarAmount": 0,
 "Email": null,
 "PayeeName": null,
 "success": true,
 "code": "OK",
 "message": "Transaction Found",
 "errors": []
}

Please note if “success=true”, the payment was collected successfully.

This will complete the transaction process.

5. NoqoodyPay Admin Panel

NoqoodyPay provides a Web portal from where merchant can monitor his daily transaction and audit reports. URL to access the portal will be provided my NoqoodyPay Admin along with its credentials

6. URL Endpoints

The URL endpoint is created by combining the base URL of the environment in which you want to execute your request, like Sandbox vs. Production, the appropriate Authorization for that environment, and the function you want to execute.

For example, https://sandbox.noqoodypay.com/api/token Live URL Endpoints will be provided by NoqoodyAdmin after successful integration with NoqoodyPay Sandbox Account