search

[NCMC] Integration via App Invoke

Sample App

Please download the sample app for NCMC integration through the App Invoke SDK. The demo contains an NCMC screen (NCMCAppInvokeActivity) that exercises every NcmcPayments method described below, as well as Printer SDK integration for generating custom receipts.

Integration Steps

 

The App Invoke SDK launches the Paytm EDC app, receives the result and returns the parsed response to your code. No manifest changes are required in your application.

 

1. Add the SDK dependency

Include the aar library provided in the Android Project and add it as a dependency in the module’s gradle file.

dependencies {
    implementation fileTree(include: ['*.aar'], dir: 'libs')
}

Once the project is synced, the NcmcPayments class can be accessed. It has methods named doReadCard, doMoneyAdd, doUpdateBalance, doCheckBalance and doCreateService.

 

2. Implement the result callback

NcmcPayments.IPaytmResult is used by the application to receive the response for every request.

val ncmcResult = object : NcmcPayments.IPaytmResult {
    override fun onResult(requestId: Int, responseData: Map<String, String>) {
        val status = responseData["status"]            // SUCCESS / FAIL
        val cardBalance = responseData["cardBalance"]  // paise
        // Process result
    }

    override fun onError(requestId: Int, errorMsg: String) {
        // e.g. "Another Request Pending", "Payment Cancelled", "Request timed out"
    }
}

 

3. Invoke the NCMC operation

To be able to invoke the Payments Application the calling application must be in foreground and thus, an instance of a live Activity is a mandatory parameter. The SDK shows a transparent loading screen while the EDC app processes the request and closes it automatically when the response arrives.

val requestId = NcmcPayments.doMoneyAdd(
    activity = this,
    paytmResult = ncmcResult,
    amountInPaise = 20000,        // ₹200.00
    orderId = "ORDER_54321",      // unique per request
    cardNoSHA = cardNoSHA,        // optional, from a previous Read Card / Check Balance
    serviceType = "CASH",         // "CASH" or "ACCOUNT"
    flowType = "transit"
)
if (requestId == NcmcPayments.ERROR_CODE) {
    // Request rejected: another request pending or invalid request. onError is also invoked.
}

 

4. Handle the response

In case of success/failure onResult is invoked with responseData containing the key-value pairs of the response (status, orderId, cardNo, cardBalance, txnId, responseTags, errorCode, errorMsg, …). The keys for each operation are listed on the [NCMC] All Supported Features page. Always read the status key; receiving onResult only means the EDC app responded.

In case of error onError is invoked with the requestId (or -101 when none is available) and an errorMsg – see Error Messages below.

 

5. Optional: Integrate Printer SDK

You can use this SDK for customised receipts. Customised receipts can be printed from the merchant application using the printer which is embedded in the Paytm POS Machine. Please see the sample project for printer sdk integration.

Method Signatures and Parameters

 

Following are the details of parameters to be used with respective methods. Optional parameters have a default value as mentioned in each method. Every method returns the requestId that will be echoed back in the callback, or -101 if the request was rejected.

 

Read Card :- To read NCMC card data (Retail / Transit)

NcmcPayments.doReadCard(
    activity: Activity,
    paytmResult: IPaytmResult,
    orderId: String,
    flowType: String,                     // "transit"
    isOsa: Boolean = false,
    readMethod: String? = null,
    requestTags: List<String>? = null,
    requestId: Int = Provided/Autogenerated
): Int - Returns the request ID

 

Add Money :- To add money to the global balance of the card using Cash / Linked Account

NcmcPayments.doMoneyAdd(
    activity: Activity,
    paytmResult: IPaytmResult,
    amountInPaise: Int,
    orderId: String,
    extendInfo: Map<String, String>? = null,
    cardNoSHA: String? = null,
    serviceType: String,                  // "CASH" or "ACCOUNT"
    flowType: String,
    requestId: Int = Provided/Autogenerated
): Int - Returns the request ID

 

Update Balance :- To update the global balance of the card when money has already been added to the host account (NetBanking, wallet, etc.)

NcmcPayments.doUpdateBalance(
    activity: Activity,
    paytmResult: IPaytmResult,
    orderId: String,
    cardNoSHA: String? = null,
    extendInfo: Map<String, String>? = null,
    flowType: String,
    requestId: Int = Provided/Autogenerated
): Int - Returns the request ID

 

Check Balance :- To read the global balance of the card along with card data

NcmcPayments.doCheckBalance(
    activity: Activity,
    paytmResult: IPaytmResult,
    orderId: String,
    flowType: String,
    requestTags: List<String>? = null,
    requestId: Int = Provided/Autogenerated
): Int - Returns the request ID

 

Create Service :- To create a Common Service Area (CSA) or Operator Service Area (OSA) on the card

NcmcPayments.doCreateService(
    activity: Activity,
    paytmResult: IPaytmResult,
    orderId: String,
    extendInfo: Map<String, String>? = null,
    flowType: String,
    isOsa: Boolean = false,
    requestId: Int = Provided/Autogenerated
): Int - Returns the request ID

 

Method Parameter Definitions :-

 

Parameter Name

Type

Optional/Mandatory

Default Value

Explanation

activity Activity Mandatory N/A Application needs to provide the Activity's instance as it needs to be in foreground to be able to access these methods. A singleTask loading Activity is launched while the request is processed and is closed automatically on response.
paytmResult NcmcPayments.IPaytmResult Mandatory N/A This is a callback interface for the application where response will be sent. It has onResult and onError callbacks for success and error scenarios.
orderId String Mandatory N/A Unique order ID for each request. Returned as is in the response. Must be non-empty.
flowType String Mandatory N/A Flow identifier passed to the EDC app. Use "transit" for NCMC transit operations (isOsa is honoured only for transit).
amountInPaise Integer Mandatory (doMoneyAdd) N/A Amount to load, in paise. Minimum 100 (₹1.00).
serviceType String Mandatory (doMoneyAdd) N/A Source of funds for Add Money. Acceptable values are "CASH" and "ACCOUNT".
cardNoSHA String Optional null SHA hash of the card number returned by a previous Read Card / Check Balance. When provided, the EDC app verifies that the tapped card is the same card.
isOsa Boolean Optional false true for Operator Service Area (OSA), false for Common Service Area (CSA). Used by doReadCard and doCreateService.
readMethod String Optional null Card read method hint for doReadCard. Acceptable values are "tap", "insert", "swipe" and "default".
requestTags List<String> Optional null EMV tags to be read from the card, e.g. listOf("5A", "DF33"). Returned in responseTags. Used by doReadCard and doCheckBalance.
extendInfo Map<String, String> Optional null Defines key value pairs that need to be recorded along with the transaction.
Note: These will not be printed on receipt.
requestId Integer Optional auto generated An ID used to identify the response with respect to the request. Can be provided by the application or autogenerated at runtime. Each method also returns this for record if required.

 

Error Messages :-

 

errorMsg

When

Another Request Pending A request is already in progress. Only one request can be active at a time.
Invalid Request Mandatory inputs failed validation (empty orderId, amountInPaise < 100).
Invalid Request Bundle The SDK Activity was started without the expected extras.
EDC app not installed: <package> The Paytm EDC app (com.paytm.pos) is not present on the device.
Payment Cancelled The user pressed BACK twice on the loading screen.
Invalid Response The EDC app returned an empty response.
Request timed out No response from the EDC app within 5 minutes.
Error Occurred Generic failure.

 

Notes :-

  • Only one NCMC request can be active at a time; a new request while one is pending is rejected with "Another Request Pending". State is reset on result, error, cancellation or timeout.
  • Both callbacks are delivered on the main thread. Validation errors are delivered synchronously, before the method returns.
  • The release AAR targets the production EDC app (com.paytm.pos); the debug AAR targets com.paytm.pos.debug.
  • Java callers: doReadCard, doMoneyAdd and doUpdateBalance expose overloads for the optional parameters; for doCheckBalance and doCreateService all parameters must be passed.
  • NcmcPayments and PaytmPayments track requests independently; do not run a retail payment and an NCMC request at the same time.