Merchant Integration Guide
1. Overview
This document provides Noqoody 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 Noqoody are encrypted with an external layer of encryption “SSL” Once you are enrolled in the Noqoody, you will be provided with a unique UserID for both a sandbox and a production environment. The Noqoody 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
Noqoody 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
Noqoody will provide a widget which a merchant can insert into the checkout page.
<script type="text/javascript"
src="//sandbox.noqoodypay.com/api/api/webpayment/getweb
jsapi/{ProjectCode}"></script>
Your project code will be provided by Noqoody 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 Noqoody 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.
http://{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 Noqoody 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
http://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
http://sandbox.noqoodypay.com/api/token
Content Type of the request will be “application/x-www-formURLencoded”
Parameters will be
“grant_type=password&username={NoqoodyUserName}&pa
ssword={NoqoodyPassword}”
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.
http://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 Noqoody 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
http://sandbox.noqoodypay.com/api/token
Content Type of the request will be “application/x-www-formURLencoded”
Parameters will be
“grant_type=password&username={NoqoodyUserName}&pa
ssword={NoqoodyPassword}”
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.
http://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.
http://{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 Noqoody 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.
http://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. Noqoody Admin Panel
Noqoody provides a Web portal from where merchant can monitor his daily transaction and audit reports. URL to access the portal will be provided my Noqoody 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,
http://sandbox.noqoodypay.com/api/token
Live URL Endpoints will be provided by NoqoodyAdmin after
successful integration with Noqoody Sandbox Account