Installation Guide - Naloff67/Mobile-XDK-RazerMS_IOS GitHub Wiki

Welcome to the Mobile-XDK-RazerMS_IOS wiki!

How to install !

Installation via CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For more detailed usage and installation instructions, visit their website https://cocoapods.org/pods/rms-mobile-xdk-cocoapods. To integrate RMS XDK into your Xcode project using CocoaPods, specify it in your Podfile:

  1. Open Terminal, Navigate to the root of your project, e.g cd /Users/razertechnical/Mobile-XDK-RazerMS_IOS/MOLPayExampleForSwift
Sample :

image

  1. input the command below to the terminal :
pod 'rms-mobile-xdk-cocoapods', '~> 3.32.1'

If you are using Swift

  1. Create a bridging header file to create one, Navigate to File > New > File...

Sample :

image

image

  1. Then in the Bridging Header file. insert #import <MOLPayXDK/MOLPayLib.h>

To install Manual for Swift

  1. Drag and drop MOLPayXDK.bundle and MOLPayXDK.framework into the application project folder to perform all imports. Please copy both files into the project. The files is provided in the example project.

  2. Create a bridging header file for MOLPay XDK Obj-c framework. Then add the bridging header file to the Swift Compiler under Objective-C Bridging Header.

  3. Add #import <MOLPayXDK/MOLPayLib.h> to the last line of the bridging header file.

Sample :

image

  1. In your ViewController.swift file, Add MOLPayLibDelegate to the ViewController class declaration.

Sample :

image

  1. Now add the below the transactionResult method, for all callbacks. you may use the example file as reference
    func transactionResult(_ result: [AnyHashable: Any]!)

image

  1. Now open your info.plist file then click on the + to add new key. choose App Transport Security Settings and press enter. In there click + to add a new key and choose Allow Arbitrary Loads. For its Value choose YES. result should look like the sample provided.

Sample :

image

  1. Now in the info.plist file click on + to add new key. put in NSPhotoLibraryUsageDescription and press enter. for its value, put in Payment images. result should like the sample provided.

Sample :

image

  1. Like the step before. repeat the process but the key will be NSPhotoLibraryAddUsageDescription. value should be Payment images. result should look like the sample provided.

Sample :

image

Prepare the Payment detail object

To Use rms-mobile-xdk-android_studio, you will need the method below.

Note : text with <> you will need to remove and place your String.

Swift

let paymentRequestDict: [String:Any] = [
    // Optional, REQUIRED when use online Sandbox environment and account credentials.
    "mp_dev_mode": NSNumber.init(booleanLiteral:false),

    // Mandatory String. Values obtained from MOLPay.
    "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",
]

Below are the optional fields, depending on your business preference you may add to the var paymentDetails object for you to use.

    // 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/rms-mobile-xdk-examples/blob/master/channel_list.tsv.
    "mp_bill_description": "billdesc",
    "mp_bill_name": "billname",
    "mp_bill_email": "[email protected]",
    "mp_bill_mobile": "+1234567",

    // Optional, allow channel selection. 
    "mp_channel_editing": NSNumber.init(booleanLiteral:false),

    // Optional, allow billing information editing.
    "mp_editing_enabled": NSNumber.init(booleanLiteral: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/rms-mobile-xdk-examples/blob/master/custom.css.
    "mp_custom_css_url": Bundle.main.path(forResource: "custom.css", ofType: nil)!,

    // 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 MOLPay Recurring API pdf. 
    "mp_is_recurring": NSNumber.init(booleanLiteral:false),

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

    // Optional, simulate offline payment, set boolean value to enable. 
    "mp_sandbox_mode": NSNumber.init(booleanLiteral: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": NSNumber.init(booleanLiteral:true),

    // Optional, extended email format validation based on W3C standards.
    "mp_advanced_email_validation_enabled": NSNumber.init(booleanLiteral:true),

    // Optional, extended phone format validation based on Google i18n standards.
    "mp_advanced_phone_validation_enabled": NSNumber.init(booleanLiteral:true),

    // Optional, explicitly force disable user input.
    "mp_bill_name_edit_disabled": NSNumber.init(booleanLiteral:true),
    "mp_bill_email_edit_disabled": NSNumber.init(booleanLiteral:true),
    "mp_bill_mobile_edit_disabled": NSNumber.init(booleanLiteral:true),
    "mp_bill_description_edit_disabled": NSNumber.init(booleanLiteral: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": NSNumber.init(booleanLiteral:true),

    // Optional, disable card list option.
    "mp_card_list_disabled": NSNumber.init(booleanLiteral:true),

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

    // Optional, allow to enable ApplePay Channel
    "mp_ap_merchant_ID": "",

For more descriptive explanation on each parameter fields, you can view the provided file below :

XDK parameters reference

Start the payment module

Swift

let mp = MOLPayLib(delegate:self, andPaymentDetails: paymentRequestDict)

Show Payment UI

Swift

self.present(nc, animated: false) {}

Close the payment module

Swift

mp.closemolpay()
  • Note: The host application needs to implement the MOLPay payment module manually upon getting a final callback from the close event.

Payment module callback

Swift

func transactionResult(_ result: [AnyHashable: Any]!) {}

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 preferable.) 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)

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

Note : You can ignore other parameters and values not stated above and it will still show results.

Sample Transaction 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.

Possible reasons

  • Internet not available
  • API credentials (username, password, merchant id, verify key)
  • Razer Merchant Services server offline.

The End

That's it! You've successfully added the Mobile-XDK-RazerMS_IOS package to your Xcode project and can now leverage its features within your application !

Note : If you ever get lost you can use the example project provided in this git so you can follow along.