fiuu-mobile-xdk-reactnative

This is Fiuu Merchant Services React Native payment module that is ready to be implemented into any React Native project npm install module. An example application project (MOLPayReactExampleProject) is provided for Razer Merchant Services XDK framework integration reference.

Recommended configurations

• Node.js Version: 5.3.0 ++

• Minimum Android SDK Version: 27 ++

• Minimum Android API level: 19 ++

• Minimum Android target version: Android 4.4

• Minimum React Navtive version : 0.47.1 ++

• Xcode version: 9 ++

• Minimum target version: iOS 8

Installation

Auto link (RN > 0.61.0)

Android

1. npm install fiuu-mobile-xdk-reactnative

2. Go to your project android->app->src. Add new file name fiuu-mobile-xdk-reactnative.d.ts.

3. Inside file fiuu-mobile-xdk-reactnative.d.ts. add the following line declare module 'fiuu-mobile-xdk-reactnative';.

iOS

1. npm install fiuu-mobile-xdk-reactnative

2. cd ios && pod install && cd ..

3. Add 'App Transport Security Settings > Allow Arbitrary Loads > YES' to the application project info.plist

4. Add 'NSPhotoLibraryUsageDescription' > 'Payment images' to the application project info.plist

5. Add 'NSPhotoLibraryAddUsageDescription' > 'Payment images' to the application project info.plist

Manual link (RN < 0.60.0)

Android

1. npm install fiuu-mobile-xdk-reactnative

2. add the following code to add the package to MainApplication.java (MainActivity.java if RN < 0.33)

import com.molpayxdk.MOLPayReactPackage; //<- this

protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            new MOLPayReactPackage() //<- this
        );
    }

3. add the following codes to your android/setting.gradle

you might have multiple 3rd party libraries, make sure that you don't create multiple include.

include ':app', ':fiuu-mobile-xdk-reactnative'
project(':fiuu-mobile-xdk-reactnative').projectDir = new File(rootProject.projectDir, '../node_modules/fiuu-mobile-xdk-reactnative/android')

4. edit android/app/build.gradle and add the following line inside dependencies

compile project(':fiuu-mobile-xdk-reactnative')

5. run react-native run-android to see if everything is compilable.

if have any issue when run-android please make sure your android/local.properties already set sdk path

ndk.dir=path/Android/sdk/ndk-bundle
sdk.dir=path/Android/sdk

6. (Optional) header include Close button in payment UI change the following codes in your android/app/src/main/res/values/styles.xml

<resources>

    <!-- Base application theme. -->
    <style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
        <!-- Customize your theme here. -->
        <!-- use any perfer color-->
        <item name="colorPrimary">#3F51B5</item>
    </style>

</resources>

IOS

1. npm install fiuu-mobile-xdk-reactnative

2. Add 'App Transport Security Settings > Allow Arbitrary Loads > YES' to the application project info.plist

3. Add 'NSPhotoLibraryUsageDescription' > 'Payment images' to the application project info.plist

4. Add 'NSPhotoLibraryAddUsageDescription' > 'Payment images' to the application project info.plist

Sample Result

=========================================
Sample transaction result in JSON string:
=========================================

{"status_code":"11","amount":"1.01","chksum":"34a9ec11a5b79f31a15176ffbcac76cd","pInstruction":0,"msgType":"C6","paydate":1459240430,"order_id":"3q3rux7dj","err_desc":"","channel":"Credit","app_code":"439187","txn_ID":"6936766"}

Parameter and meaning:

"status_code" - "00" for Success, "11" for Failed, "22" for *Pending. 
(*Pending status only applicable to cash channels only)
"amount" - The transaction amount
"paydate" - The transaction date
"order_id" - The transaction order id
"channel" - The transaction channel description
"txn_ID" - The transaction id generated by Razer Merchant Services

* Notes: You may ignore other parameters and values not stated above

=====================================
* Sample error result in JSON string:
=====================================

{"Error":"Communication Error"}

Parameter and meaning:

"Communication Error" - Error starting a payment process due to several possible reasons, please contact Razer Merchant Services support should the error persists.
1) Internet not available
2) API credentials (username, password, merchant id, verify key)
3) Razer Merchant Services server offline.

Prepare the Payment detail object

var paymentDetails = {
    // Optional, REQUIRED when use online Sandbox environment and account credentials.
    'mp_dev_mode': false,

    // Mandatory String. Values obtained from Razer Merchant Services.
    'mp_username' : 'username',
    'mp_password' : 'password',
    'mp_merchant_ID' : 'merchantid',
    'mp_app_name' : 'appname',
    'mp_verification_key' : 'vkey123', 

    // Mandatory String. Payment values.
    'mp_amount' : '1.10',, // Minimum 1.01
    'mp_order_ID' : 'orderid123', 
    'mp_currency' : 'MYR',
    'mp_country' : 'MY',  
    
    // Optional String.
    'mp_channel' : '', // Use 'multi' for all available channels option. For individual channel seletion, please refer to https://github.com/RazerMS/molpay-mobile-xdk-examples/blob/master/channel_list.tsv.
    'mp_bill_description' : '',
    'mp_bill_name' : '',
    'mp_bill_email' : '',
    'mp_bill_mobile' : '',
    'mp_channel_editing' : false, // Option to allow channel selection.
    'mp_editing_enabled' : false, // Option to allow billing information editing.
    
    // Optional, but required payment values. User input will be required when values not passed.
    'mp_channel' : 'multi', // Use 'multi' for all available channels option. For individual channel seletion, please refer to https://github.com/RazerMS/molpay-mobile-xdk-examples/blob/master/channel_list.tsv.
    'mp_bill_description' : 'billdesc',
    'mp_bill_name' : 'billname',
    'mp_bill_email' : 'email@domain.com',
    'mp_bill_mobile' : '+1234567',

    // Optional, allow channel selection. 
    'mp_channel_editing' : false,

    // Optional, allow billing information editing.
    'mp_editing_enabled' : false,

    // Optional, for Escrow.
    'mp_is_escrow': '0', // Put "1" to enable escrow

    // Optional, for credit card BIN restrictions and campaigns.
    'mp_bin_lock' : ['414170', '414171'],   

    // Optional, for mp_bin_lock alert error.
    'mp_bin_lock_err_msg': 'Only UOB allowed',
    
    // WARNING! FOR TRANSACTION QUERY USE ONLY, DO NOT USE THIS ON PAYMENT PROCESS.
    // Optional, provide a valid cash channel transaction id here will display a payment instruction screen. Required if mp_request_type is 'Receipt'.
    'mp_transaction_id': '',
    // Optional, use 'Receipt' for Cash channels, and 'Status' for transaction status query.
    'mp_request_type': '',

    // Optional, use this to customize the UI theme for the payment info screen, the original XDK custom.css file can be obtained at https://github.com/RazerMS/molpay-mobile-xdk-examples/blob/master/custom.css.
    'mp_custom_css_url': '',

    // Optional, set the token id to nominate a preferred token as the default selection, set "new" to allow new card only.
    'mp_preferred_token': '',

    // Optional, credit card transaction type, set "AUTH" to authorize the transaction.
    'mp_tcctype': '',

    // Optional, required valid credit card channel, set true to process this transaction through the recurring api, please refer the Razer Merchant Services Recurring API pdf. 
    'mp_is_recurring': false,

    // Optional, show nominated channels.
    'mp_allowed_channels': ['credit', 'credit3'],

    // Optional, simulate offline payment, set boolean value to enable. 
    'mp_sandbox_mode': true,

    // Optional, required a valid mp_channel value, this will skip the payment info page and go direct to the payment screen.
    'mp_express_mode': true,

    // Optional, extended email format validation based on W3C standards.
    'mp_advanced_email_validation_enabled': true,

    // Optional, extended phone format validation based on Google i18n standards.
    'mp_advanced_phone_validation_enabled': true,

    // Optional, explicitly force disable user input.
    'mp_bill_name_edit_disabled': true,
    'mp_bill_email_edit_disabled': true,
    'mp_bill_mobile_edit_disabled': true,
    'mp_bill_description_edit_disabled': true,

    // Optional, EN, MS, VI, TH, FIL, MY, KM, ID, ZH.
    'mp_language': 'EN',

    // Optional, Cash channel payment request expiration duration in hour.
    'mp_cash_waittime': 48,
    
    // Optional, allow bypass of 3DS on some credit card channels.
    'mp_non_3DS': true,

    // Optional, disable card list option.
    'mp_card_list_disabled': true,

    // Optional for channels restriction, this option has less priority than mp_allowed_channels.
    'mp_disabled_channels': ['credit']  
    
};

Start the payment module

//import Razer Merchant Services package
import payment from 'fiuu-mobile-xdk-reactnative';

//start Razer Merchant Services payment
payment.startMolpay(paymentDetails, function(data){
    //callback after payment success
    console.log(data);
});

React Native android below than 0.47.1 build error

Navigate to node_modules/fiuu-mobile-xdk-reactnative/android/src/main/java/com/molpayxdk/MOLPayReactPackage.java and add the below code.

    @Override
    public List<Class<? extends JavaScriptModule>> createJSModules() {
        return Collections.emptyList();
    }

Google Pay integration

Prepare paymentDetails :

// TODO: Add these on Google Pay tap action

var paymentDetails = {
    /*
    TODO: Follow Google’s instructions to request production access for your app: https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access
    *
    Choose the integration type Gateway when prompted, and provide screenshots of your app for review.
    After your app has been approved, test your integration in production by set mp_sandbox_mode = false & use production mp_verification_key & mp_merchant_ID.
    Then launching Google Pay from a signed, release build of your app.
    */
    'mp_sandbox_mode': true,
    
    // TODO : Enter your credentials
    'mp_merchant_ID': '',
    'mp_verification_key': '',
    
    'mp_order_ID': 'order1234567890', // Unique order id
    'mp_currency': 'MYR',
    'mp_country': 'MY',
    
    'mp_amount': '1.23', // Minimum 1.00 must be in 2 decimal points format
    'mp_bill_description': 'Test Google Pay',
    'mp_bill_name': 'Google Pay',
    'mp_bill_email': 'testing@gmail.com',
    'mp_bill_mobile': '123456789',
    
    'mp_extended_vcode': false, // Optional : Set true if your account enabled extended Verify Payment
};

//import Razer Merchant Services package
import payment from 'fiuu-mobile-xdk-reactnative';

//start Razer Merchant Services payment
payment.startMolpay(paymentDetails, function(data){
    //callback after payment success
    console.log(data);
});

Payment results - Google Pay

=========================================
Sample transaction result in JSON string:
=========================================

{
    "StatCode":"00",
    "StatName":"captured",
    "TranID":"30824452",
    "Amount":"1.11",
    "Domain":"SB_molpayxdk",
    "VrfKey":"7c34xxxxxxxxxxxxxxxxxxxxxxxx2000",
    "Channel":"credit",
    "OrderID":"1717661730213",
    "Currency":"MYR",
    "ErrorCode":null,
    "ErrorDesc":null
}

Parameter and meaning:

"StatCode" - "00" for Success, "11" for Failed, "22" for Pending. 

"Amount" - The transaction amount
"OrderID" - The transaction order ID
"Channel" - The transaction channel description
"TranID" - The transaction ID generated by Fiuu
"Domain" - Your Merchant ID

"VrfKey" - You can verify payment using this formula -> VrfKey = md5(Amount+secret_key+Domain+TranID+StatCode)

* Note: secret_key = Your account Secret Key in https://portal.fiuu.com/
* Notes: You may ignore other parameters and values not stated above

=====================================
* Sample error result in JSON string:
=====================================

{
    "status":false,
    "error_code":"P03",
    "error_desc":"Your payment info format not correct."
}

{
    "error_code" = A01;
    "error_desc" = "Fail to detokenize Google Pay Token given";
    status = 0;
}

Parameter and meaning:

Error P03 - Your payment info format not correct   
1) Need makesure all required parameters filled correctly.
2) Need set mp_extended_vcode = true if enabled extended Verify Payment.

Error A01 - "Fail to detokenize Google Pay Token given" - Error starting a payment process due to several possible reasons, please contact Razer Merchant Services support should the error persists.
1) Misconfigure GooglePay setup
2) API credentials (username, password, merchant id, verify key)
3) Razer Merchant Services server offline.

Cash channel payment process (How does it work?)

This is how the cash channels work on XDK:

1) The user initiate a cash payment, upon completed, the XDK will pause at the “Payment instruction” screen, the results would return a pending status.

2) The user can then click on “Close” to exit the Razer Merchant Services XDK aka the payment screen.

3) When later in time, the user would arrive at say 7-Eleven to make the payment, the host app then can call the XDK again to display the “Payment Instruction” again, then it has to pass in all the payment details like it will for the standard payment process, only this time, the host app will have to also pass in an extra value in the payment details, it’s the “mp_transaction_id”, the value has to be the same transaction returned in the results from the XDK earlier during the completion of the transaction. If the transaction id provided is accurate, the XDK will instead show the “Payment Instruction" in place of the standard payment screen.

4) After the user done the paying at the 7-Eleven counter, they can close and exit Razer Merchant Services XDK by clicking the “Close” button again.

XDK built-in checksum validator caveats

All XDK come with a built-in checksum validator to validate all incoming checksums and return the validation result through the "mp_secured_verified" parameter. However, this mechanism will fail and always return false if merchants are implementing the private secret key (which the latter is highly recommended and prefereable.) If you would choose to implement the private secret key, you may ignore the "mp_secured_verified" and send the checksum back to your server for validation. 

Private Secret Key checksum validation formula

chksum = MD5(mp_merchant_ID + results.msgType + results.txn_ID + results.amount + results.status_code + merchant_private_secret_key)

Support

Submit issue to this repository or email to our support-sa@fiuu.com

Merchant Technical Support / Customer Care : support@fiuu.com Sales/Reseller Enquiry : sales@fiuu.com Marketing Campaign : marketing@fiuu.com Channel/Partner Enquiry : channel@fiuu.com Media Contact : media@fiuu.com R&D and Tech-related Suggestion : technical@fiuu.com Abuse Reporting : abuse@fiuu.com