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.
[NCMC] Integration via App Invoke
Sample App
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.