Online Merchant Payment Service

Online Merchant Registration Process

  1. Call our Sales Team on 220 or visit one of our Point of Sales throughout Iraq to register for an Online Merchant account with AsiaHawala.
  2. You will receive an SMS containing the Temporary PIN.
  3. First step is to change Temporary PIN for your wallet by dialling *212#.
  4. You will also receive username and temporary password via an SMS, login to your account online and change your password, to change temporary password you will need received username, password and last 4 digits of ID supplied during registration.
  5. After registering your wallet contact our sales and they will sign you up for Merchant Panel account.
  6. When Merchant Panel account complete you will receive an automatic email containing instruction on how to setup and connect to payment service, the email also include username and password to access Merchant Panel.

Integration

AsiaHawala payments provides payment buttons as a quick and easy solution, payment buttons let you securely accept payments from subscribers of AsiaHawala.

The merchants have option to use our payment service solution for their websites and mobile apps or integrate using our API, the API is available for merchant who like to develop the payment service suit their requirements.

1. Web Applications

1.1 Standard Payment Button

AsiaHawala standard button designed for merchant who want to integrate with minimum development, just by including the code snippet and setting a few parameters your application is connected to our payment service.

Button Features

The localization of button supported for English, Arabic and Kurdish, to changing the language of a button can be done by setting the variable data-language with the correct language code. There are three sizes for plugging button small, medium, and large, use the button size you prefer for your website.

Button Size  Plugging URL
Large Button src="https://pay.asiahawala.net/payment/checkout.large.js
Medium Button src="https://pay.asiahawala.net/payment/checkout.medium.js
Small Button src="https://pay.asiahawala.net/payment/checkout.small.js

Language Setting

There are three parameters for languages Arabic, Kurdish and English (en_US, ar_IR and ku_IR.).

The websites with multiple language support English, Kurdish and Arabic can set language of button, this parameter will affect tow things.

  • Button language. if your website support multiple languages, pass the language code en_US, ar_IR or ku_IR  to change the text Pay Now and AsiaHawala.
  • When users click on Pay Now, if language code set to ar_IR the Online Payment Service website shown in Arabic.

Arabic

Kurdish

English

Copy the following code snippet and past the code at checkout page.

<script async="async"  src="https://pay.asiahawala.net/api/checkout.small.js? 
       merchant=true”
       data-merchantkey = "Past your token  here" 
       data-amount= “Total amount for products purchased”
       data-currency= “Currency Code here"         
       data-language = “Language code, there are three supported  languages” 
       data-transactionid= “Merchant unique  Transaction IQ” 
       data-callback= “return URL where you can get parameters  after transaction processed” ></script>

Parameter    Description
data-merchantkey TThe token sent by email during registration of Merchant Panel, you can also get your token by login to Merchant Panel and click on view Token.Token is static not changeable.
data-amount Total mount for products purchased
data-currency Currency code, merchant can log in to Merchant panel and see what currencies available and get currency code default currency code is IQD. It is merchant responsibility to set exchange rate.
data-language If your website is multilingual you can set language for both Plugin Button and AsiaHawala Payment website, three languages supported language codes is en_US, ar_IR and ku_IR.
data-transactionid This is Merchant unique transaction ID.
IMPORTANT:  you must make sure that you are passing unique transaction ID.
data-callback The return URL, this is required to send you transaction response, you can catch the parameters when transaction complete and check transaction ID on your system and make transaction status check by calling our API before login transaction on your system. Please see Transaction Response section

Transaction Response

Customers will receive an SMS and notification to confirm transaction after initiating a payment online, the customer can enter PIN when receiving notification or dial *212# to access notification then enter PIN to confirm transaction.

Payment confirmation callback URL looks like

After a customer confirming the transaction by entering PIN, the customer redirected to merchant website and the following parameters with transaction information are retuned to call back URL.

https://merchant’s-Callback-URL.com?FTXNID=Ah5878655&transId=MP170406.1247.C00174&statusCode=TF&amountIQD=1259.9&amountForeignCurrency=10.00&exchangeRate=125.99&foreignCurrency=USD 

Call back URL Parameters descriptions

Retuned Parameters Descriptions
FTXNID Merchant transaction ID
transId AsiaHawala transaction ID
statusCode For successful transaction, TS returned
For failed transaction, TF returned
For all other status, AF returned
amountIQD Currency is in IQD.
amountForeignCurrency Amount passed in foreign currency
exchangeRate Exchange rate set by merchant through Merchant Panel
foreignCurrency Currency code

Getting Your Merchant Token

The merchant token sent to you by an email, if you have not received the email please login to your Merchant Panel and click on view token link to get your token copy and past the token in data-merchantkey in plugin button script.

1.2 Custom Paymnet Button

Merchants may prefer to create their own button to suit their website layout and design. The developer of the merchant can create a form with custom button and POST the following information to Payment Gateway to establish connection.

Parameters Description
merchantkey The token sent by email with Merchant Panel username and password when merchant opened Merchant Panel account.
Token is static not changeable.
amount Total mount for products purchased
currency_code Currency code, merchant can log in to Merchant panel and see what currencies available and get currency code default currency code is IQD. It is merchant responsibility to set exchange rate.
lc If your website is multilingual you can set language for both Plugin Button and AsiaHawala Payment website, three languages supported language codes is en_US, ar_IR and ku_IR.
transactionid This is Merchant unique transaction ID.
IMPORTANT:  you must make sure that you are passing unique transaction ID.
notify_url The return URL, this is required to send you transaction response, you can catch the parameters when transaction complete and log these information on your own database if required. Please see Transaction Response section.

1.3 Transaction Status Check API

Checking status of transaction is very important to confirm payment was successful before making any changes to their system, both websites and mobile apps integration must call our API to check status of transaction. When transaction confirmed by entering the PIN the parameters above returned to call back URL, the merchant website must catch the transaction ID and check if this transaction ID is valid.

Example of Transaction Status check in PHP

 
	   <?php 
	    /***              
	    The  following is an example of CURL code in PHP to check status of transaction,  making CURL call is very simple and can be achieved in all programming  languages. 
	    -  Check if parameters are returned when  customer finished payment and redirected before making an API call 
	    -  check if Customer transaction ID is existing in your system before making an  API call 
	    -  make a CURL request to check the status of the transaction. 
	   #if transaction exists then log the transaction in your  system and in Success message to customer
	   #if failed show message user to customer 
	   ***/                                                                                                                                                              
	    $transaction_ID  = ‘Assign Transaction ID’;                                                        //Set transaction ID 
	    $merchant_code =  ‘PUT Your Marchant Code’;                                             //Set Merchant code 
	    $merchant_token  =’PUT Your Token Here’;                                                     //Set Merchant Token the  same as merchantkey 
	    /*** Change as appropriate 
	    Testbed  or Sandbox Environment API url:               
	    $url  =  ‘we will share URL when needed’;
	    Live or Production Environment API url:                 
	    $url  =  “we will share URL when needed” ;
	    ***/               
	    $url =   “we will share URL when needed” ;
	    //check transaction parameters returned and  compare transaction id to your transaction ID before calling API 
   if(isset($_GET['FTXNID'])  && isset($_GET['transId']) && isset($_GET['statusCode'])) 
	    { 
		 
	    //  check if transaction ID is existing on your system, if no transaction id is existing  then show message or redirect to error page  
		   
	   $request  = curl_init(); 
	     curl_setopt_array($request,  array( 
	     CURLOPT_URL => $url, 
	     CURLOPT_POST => TRUE, 
	     CURLOPT_POSTFIELDS =>  http_build_query(array 
	     (
	     'merchantCode'  => $merchant_code,  //Merchant Code  
	     'token'  => $merchant_token ,               //Merchant  Token
	     'transaction_id'  => $transaction_ID      // Merchant  transaction ID
	     )),
	     CURLOPT_RETURNTRANSFER  => TRUE
	     ));
	     $json_response  = curl_exec($request);
	     $status  = curl_getinfo($request, CURLINFO_HTTP_CODE);
	     $error  = curl_error($request);
	     curl_close($request);
	     $response  = json_decode($json_response,true);
	     if(isset($response)  && isset( $response['statusValue'][0])   && isset( $response['statusCode'][0]))
	     { 
	     if(isset($response) &&  $response['statusValue'][0] == 'SUCCESS' && $response['statusCode'][0]  == 'TS'){
	     /****  SUCESSFUL ***/
	     /*  Payment done
	     - Log or update customer’s transaction,  update system database
	     - show appropriate successful message to  customer. */
	     echo 'transaction successful';
	     }else{
	     /****  FAILD 
	     The transaction is not successful, the user  has not confirmed the transaction or payment is not complete 
	     Show appropriate error message to user.  */
	     echo 'transaction Failed';
	     }
	     }else
	     {
	     // redirect user to error  page or show an error message because no parameters supplied
	     echo 'There was a problem,  please contact administrator;
	     }
	     ?> 
	  

2. Mobile Apps

The following instruction explains how to integrate Online Payment Service using inappbrowser into mobile application for both Android and IOS

The developer is free on design and styling of button that suit mobile application, the developer is responsible for setting all form parameters and sending POST request to Payment Service website with all parameters.

Payment Button

AsiaHawala payment button is a easy to integrate into your code. Just Integrated the button in your app and pass the form values which is required to proceed your request.

The button has the following parameters.

  1. Merchant Token (merchantkey): Merchant token is a hidden unique value specifically generated for particular merchant which is registered on AsiaHawala Merchant Panel, the token value is static and set by developer during integration.
  2. Amount (amount): Total price of products purchased.
  3. Currency (currency_code): the currency which merchant deals with. For example, USD. the Currency Code value set by developer during integration. Currency rate are set by merchants for each currency code, it is three letter currency code you can log in to merchant panel and get currency code.
  4. Language (lc): Language Code of Payment Service, the Online Payment Service has support for three languages English (en_US), Arabic (ar_IR) and Kurdish (ku_IR).
  5. Transaction id (transactionid): Merchant unique transaction ID, merchant generated value to track transaction, it’s integrated by developer.
  6. Call Back URL (notify_url): Final URL where we can get the status of our transaction, the developer will fetch results returned to URL and can log these information on their system.

Note: All these variables are dynamic and needs to be handled properly by development team. User can get transaction id after the completion of particular transaction. All these variables are defined by the developer while implementing the button into application.

Currently system supports only 3 language

The following values for language defines wat version of Payment service website will be shown to user.

  • English       (Language code: en_US)
  • Arabic        (Language Code: ar_IR)
  • Kurdish       (Language Code: ku_IR)

Mobile Integration Flow

  • When user clicks on Pay Now button. The user redirects to inappbrowser (android webview or IOS webview) and Online Payment service loaded.
  • The developer creates a dynamic URL and adds all parameter values, when button clicked the URL created and all parameters posted to Online Payment Service.
  • Online Payment service extracts all Parameters, after processing request the Online Payment website shown in inappbrowser.
  • The user enters mobile number and click on Pay Now button.
  • An SMS sent to user to enter PIN to confirm transaction.
  • A USSD push notification sent to user to enter PIN to confirm transaction.
  • The user enters the PIN, the transaction processed and payment information posted to callback URL.
  • When the whole process flow is processing in (android or IOS) webview and our app monitors each and every request URL. When we track the callback URL the inappbrowser closed and jumps back to native app.
  • The developer can extract the information and log the information on their system.

With the POST data

{ 
  "merchant":"true",                                                                   
  " merchantkey ":" Past your token here ", 
  "amount":" Total amount for  products purchased ", 
  "currency_code”: “Three letter Currency  Code", 
  "lc":" Language code, there  are three supported languages ", 
  "transactionid":" Merchant’s unique  Transaction IQ ", 
  "notify_url":" return URL where you  can get parameters after transaction processed " 
      }

Note: The whole process flow is processing in android webview and our app monitors each and every request URL. The developer can fetch the transaction response and log them in their system.

Transaction Response

When customers enter the PIN on their mobile after receiving the push notification or dialling *212# then entering the PIN, the user redirected to merchant return URL assigned to notify_url. The developer is responsible for fetch calling transaction status check API before making any changes on merchant system. Please see Transaction Status Check API for more detail.

Note: Please see "Call back URL Parameters descriptions" section for more details.

2.1 Android Integration

<Button 
  android:id="@+id/paynow_button" 
  android:text="@string/pay_now" 
  android:layout_width="wrap_content" 
  android:layout_height="wrap_content" 
  android:layout_margin="10dp" 
  style=”@style/arabic_large”/>

On Button Click we will process the data in web view

Here is the sample code where we will process our request:

    
  private String postData; 
    private String merchantKey = "put your token  here"; 
    private String webURL = "https://pay.asiahawala.net/payments/payments"; 
    String amount = “Total amount for products  purchased”; 
    String currency = “Currency Code here";  
    String language = “Language code, there are three  supported languages”; 
    String transaction = “Merchant unique Transaction  ID” 
    String notifyURL= “Merchant notify url” 
   postData = "merchantkey=" + merchantKey  + "&currency_code=" + currency + "&amount=" +  amount + "&transactionid=" + transaction +"&lc=" +  language + "&notify_url=" + notifyURL; 
   webView.postUrl(webURL,  EncodingUtils.getBytes(postData, "BASE64"));

Sample Class to track inappbrowser URL

  

/*
WalletWebClient is android activity class which tracks the AsiaHawala payment process request * URL in native app.
*/

private class WalletWebClient extends WebViewClient {        @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)        @Override        public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {            showLogs(request.getUrl().toString());            return super.shouldOverrideUrlLoading(view, request);        }        @Override        public void onPageStarted(WebView view, String url, Bitmap favicon) {            super.onPageStarted(view, url, favicon);            loadingbar.setVisibility(View.VISIBLE);            showLogs(url);            if (url.equals(Server.FAILURE_URL) || url.equals(Server.SUCCESS_URL)) { Intent intent = new Intent(); intent.putSerializable("data", all_data) setResult(RESULT_OK, intent); finish();            }        }        @Override        public void onPageFinished(WebView view, String url) {            super.onPageFinished(view, url);            loadingbar.setVisibility(View.INVISIBLE);        }        @Override        public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {            super.onReceivedError(view, errorCode, description, failingUrl);            finish();        }    }

Sample Class to Handle Response in Native App

/** *  MainActivity is android activity class which handle the response the WalletWebClient *  and update the UI on the basis of transaction status. */

public class MainActivity extends Activity{ public void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == 1){         if(resultCode == RESULT_OK) {         ModelClass  model = data.getExtras().getSerializable(“data”);           updateUI();         }     } } }

2.2 IOS Integration


      UIButton  *paynow_button = [UIButton buttonWithType:UIButtonTypeCustom]; 
    [paynow_button  setTitle:NSLocalizedString(@"pay_now", nil)  forState:UIControlStateNormal]; 
     CGSize size =  [NSLocalizedString(@"pay_now", nil) sizeWithAttributes: 
                   @{NSFontAttributeName:  [UIFont systemFontOfSize:15.0f]}]; 
     [paynow_button  setFrame:CGRectMake(0,0,size.width, size.height)]; 
     [paynow_button  setFrame:CGRectMake(0,0,size.width, size.height)]; 
     [paynow_button  setTitleColor:[UIColor whiteColor] forState:UIControlStateNormal];    
     [paynow_button  setBackgroundColor:[UIColor blueColor]]; 

On Button Click we will process the data in web view

Here is the sample code where we will process our request:

 NSString *postData; 
     NSString *merchantKey =  @"PUT YOUR TOKEN HERE "; 
     NSString *webURL =  @"https://pay.asiahawala.net/payments"; 
     NSString *amount = @"Total  amount for products purchased"; 
     NSString *currency =  @"Currency Code here"; 
     NSString *language =  @"Language code, there are three supported languages"; 
     NSString *transaction =  @"Merchant unique Transaction ID"; 
     NSString *notifyURL =  @"Merchant notify url"; 
      
     postData = [NSString           stringWithFormat:@"merchantkey=%@&currency_code=%@&amount=%@&transactionid=%@&lc=%@             &notify_url=%@",merchantKey,currency,amount,transaction,language,notifyURL]; 
        NSURL *url = [NSURL URLWithString: webURL]; 
     NSMutableURLRequest *request = [[NSMutableURLRequest alloc]initWithURL:  url]; 
     [request setHTTPMethod: @"POST"]; 
     [request setHTTPBody: [postData dataUsingEncoding:  NSUTF8StringEncoding]]; 
     [_webView loadRequest: request]

Sample Class to track inappbrowser URL

/**
*  WalletWebViewController is iOS view controller class which tracks the AsiaHawala payment process request *   url in native app.
*/

WalletWebViewController.h #import <UIKit/UIKit.h> @interface WalletWebViewController : UIViewController<UIWebViewDelegate> {                  NSString *urlString; } @property (nonatomic,copy) void  (^statusUpdate) (NSDictionary *); @property (nonatomic, strong) NSString *urlString; @property (strong, nonatomic) IBOutlet UIWebView *webView; @end WalletWebViewController.m #import "WalletWebViewController.h" @interface WalletWebViewController () @end @implementation WalletWebViewController @synthesize urlString;

#define SUCCESS_URL               @"https://www.asiahawala.com/success" #define FAILURE_URL                 @"https://www.asiahawala.com/failure" - (void)viewDidLoad {      [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;       self.webView.delegate = self;      NSURL *url = [NSURL URLWithString:self.urlString];      [self.webView loadRequest:[NSURLRequest requestWithURL:url]]; } - (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType { NSString *URLString = [[request URL] absoluteString]; if ([URLString isEqualToString:FAILURE_URL] || [URLString isEqualToString:SUCCESS_URL]) { NSDictionary *dataDictionary = [response objectForKey:@”response”];           _statusUpdate(dataDictionary); } return YES; } - (void)webView:(UIWebView *)webView didFailLoadWithError:(NSError *)error {      [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;      NSLog(@"Some error occured."); } - (void)webViewDidFinishLoad:(UIWebView *)webView;{      [UIApplication sharedApplication].networkActivityIndicatorVisible = NO; }

Sample Class to Handle Response in Native App

 
   

/** ActivityViewController is iOS parent view controller class which handles response from WalletWebViewController.
*   and update the UI on the basis of transaction status.
*/

- (void) handleResponse { WalletWebViewController *viewController = [[ WalletWebViewController alloc] initWithNibName:@"WalletWebViewController" bundle:nil];   [viewController setStatusUpdate:^(NSDictionary * response) {       NSInteger requestCode = [response objectForKey:@"requestCode"];       if([requestCode == 1)       {           if(resultCode == RESULT_OK) {               ModelClass  *model = [[ModelClass alloc] init];//data.getExtras().getSerializable(“data”);               model.dataDictionary = response;               [self updateUI];           }       }   }]; }

3. API Integration

The merchant may integrate to our payment service by using our soup API to develop their own solution, the merchant is responsible for handling development and cost. To integrate using our API you will need to have Soup URL link to our Development platform once development completed then we can give you production Soup link.

Online Payment Process

  1. The user click on Pay Now button on merchant website.
  2. User redirected to AsiaHawala payment service.
  3. The user enters mobile number and click on Pay Now, then redirected to page where asked to enter PIN on mobile.
  4. SMS sent to user to enter his PIN to confirm transaction.
  5. Push notification send to user mobile to enter his PIN, if push notification not shown dial *212# to see the notification.
  6. The user enters the PIN and press Send/Reply to confirm transaction.
  7. Push notification shown confirming the transaction.
  8. User also receives an SMS confirming the transaction.
  1. The user click on Pay with AsiaHawala button on merchant website or app
  2. User redirected to AsiaHawala payment service
  1. The user enters mobile number and click on Pay Now, then redirected to bellow page where asked to enter PIN on mobile.
When user confirms transaction the user redirected to merchant website and transaction information also posted to merchant website.
  1. SMS sent to user to enter his PIN to confirm transaction
  2. Push notification send to user mobile to enter his PIN
  3. The user enters the PIN and press Send/Reply to confirm transaction
  4. Push notification shown confirming the transaction
  5. User also receives an SMS confirming the transaction