Paytm Native Payment - Overview

  • Paytm Native checkout provides users with a redirection-less, streamlined, mobile-ready payment experience. With Paytm Native flow, merchant can improve your success rate to 6-7%. In this flow, Paytm facilitates real time success rates of paymode and cards selected. This can be used by merchant to adequately communicate/disable low performing payment modes for the customer. Paytm Native checkout empowers non PCI-DSS complaint merchants to allow their customers to select the payment mode and enters payment details on their website.

  • The following payment modes are supported in the Paytm Native.

    1. Credit Card
    2. Debit Card
    3. Net Banking
    4. UPI
    5. Paytm Wallet
    6. Paytm Postpaid
    • Customer Flow
    • Native Sequence Documentation API
    • Product Flow via SDK
    In Store Banner
    In Store Banner
  • This section details out the use cases of all APIs used in this payment flow. here.

    API Name with signature linkPurpose
    Initiate Transaction APITo get transaction token which is used in all the subsequent requests. Transaction token received is valid for one transaction and self - expires after 15 minutes. For transaction which are not completed in 15 minutes, a fresh token will be required. Checksumhash is an input parameter for this API which is generated at server end
    Fetch Payment Options
    1. Provision of payment modes - To get payment options (Credit, debit card, NB, UPI, EMI & Paytm proprietary instruments) configured on that particular merchant during debit transaction & add money transaction. Payment options for debit transaction are provided in “merchantpayoption” parameter and addmoney transactions in “addmoneypayoption” parameter
    2. Provision of saved cards –There are two types of saved cards – Saved for a customer transacting at the merchant & saved for a customer in Paytm ecosystem. In case customer is logged in to Paytm ecosystem (via login APIs), both types of saved cards will be provided. If not, only one saved at merchant level will be provided
    3. Netbanks – Only top 5 popular netbanks are provided
    4. Low success rate identifier - It also points the payment options and saved card details where current success rate is low
    Fetch NB Channels
    1. To get list of net banks which are configured for the merchant during transaction or add money transaction. In case of debit trasnactions, type parameter is merchant and also in add money transactions it is merchant
    2. It also points the banks where current success rate is low
    Fetch Bin Details
    1. Validate the 6 digit BIN of card number being entered by user
    2. Fetch card details like issuing bank, network (VISA, Master, Rupay), card type (credit, debit) etc
    3. Points the BIN where current success rate is low
    Login Send OTPCustomers who want to pay via saved card on Paytm or via Paytm proprietary instruments have to login in Paytm. Login is facilitated via OTP validation. This API is used to send OTP to customer's mobile number
    Login Validate OTPValidate the OTP sent
    Fetch Balance InfoFetch balance in customer’s Paytm proprietary instrument. Customer balance information can be fetched through this API, available balance will decide if request type in process transaction will be Add & Pay or Default
    Process Transaction
    1. To make the withdraw call from selected instrument
    2. If user balance is insufficient, to add money to Paytm proprietary instruments
    3. In case merchant wants to save the payment instrument (saved card), same can be controlled by storeinstrument parameter
    Status Query API
    1. For terminal state (success/fail) transactions, merchant is required to re-verify transaction status with this API. The status provided in the response should be treated as the final status of transaction. Additionally merchant should match the TXN Amount received with that sent in transaction request API. In case of mismatch, merchant should mark this transaction as disputed and raise it to KAM/helpdesk team
    2. In event of a network failure or genuine user dropout during the payment process, response of transaction request is not posted to the merchant. Hence in case merchant does not receive the response after considerable time has passed, it should status query after regular intervals till the terminal status of transaction is received
    3. Sometimes “pending” status is received from banks which is passed in response to the merchants. In these cases too, merchant should status query at regular intervals till the terminal status of transaction is received
    Refund API*To initiate refund transaction
    Refund Status API
    1. For terminal state (success/fail) refund transactions, merchant is required to re-verify refund transaction status with this API. The status provided in the response should be treated as the final status of refund transaction. Additionally merchant should match the TXN Amount received with that sent in refund transaction request API. In case of mismatch, merchant should mark this refund transaction as disputed and raise it to KAM/helpdesk team
    2. In event of a network failure or genuine user dropout during the payment process, response of refund transaction request is not posted to the merchant. Hence in case merchant does not receive the response after considerable time has passed, it should status query after regular intervals till the terminal status of refund transaction is received
    3. Sometimes “pending” status is received from banks which is passed in response to the merchants. In these cases too, merchant should status query at regular intervals till the terminal status of refund transaction is received

    * Note – The refund request can fail due to insufficient funds in Merchant Payable Account (MPA). MPA is unsettled merchant balance present with Paytm

    1. Gradle Dependency: Add the below dependency in app module build.gradle file.

      compile 'com.paytm.nativesdk:nativesdk:1.3.2'

    2. Add the INTERNET and ACCESS_NETWORK_STATE permissions to your AndroidManifest.xml
                                                          
                                                              
                                                          
                                                      
    3. How to initiate SDK:
      1. Obtain the PaytmSDK instance from it’s parameterised constructor. You can obtain the same for Staging, Production service depending upon your need.
      2. Parameters of constructor are:
        1. Context: Pass the application context or your activity context.
        2. IntiateTransactionResponse: Pass the whole JSON response as a string of initiate transaction api which contains: Transaction Token, RequestTimestamp, ResultCode,authentication etc.
        3. PaytmSDKCallbackListener: Callback listener where SDK will give all the results.
        4. TransactionAmount: Amount of transaction to be proceed.
        5. MerchantID: Merchant Unique ID you got while registration as Merchant on Paytm.
        6. OrderId: Unique OrderId generated for particular transaction. This should be generated at your own server
        7. MerchantName: Pass your organisation name as a string.
        8. DrawableLogo: Pass the Drawable integer of your Logo.
        9. Server: Pass the Server type of which you want to obtain the instance of. This is Enum contains values: STAGING, PRE_PRODUCTION, PRODUCTION
      3. Call the startTransaction() method to proceed to payment flow, and wait for the results in callback.
                                                                    
                                                                        Sample Code:
                    
                                                                            PaytmSDK paytmSDK = new PaytmSDK(this, intiateTransactionResponse, paytmSdkCallBackListener, amount, merchantId, orderId, “Spice Jet”, R.drawable.paytm_wallet, Server.PRODUCTION);
                                                                            
                                                                            NOTE: In case of SDK callbackUrl is a mandatory parameter kindly use below values.
                                                                    
                                                                    
                                                                
      4. PaytmSDKCallbackListener: Below are the methods to implement:
        1. someUIErrorOccured: Calls when any UI error occurred.
        2. onTransactionResonse: Calls on successful transaction or failure transaction with proper json as input.
        3. networkError: Calls when transaction failed due to network connection error.
        4. clientAuthenticationFailed: Will be used in near future.
        5. onErrorLoadingWebPage: Calls when any page don’t get load at last on webview.
        6. onBackPressedCancelTransaction: Calls when user cancel the transaction by pressing back press.
        7. onTransactionCancel: Calls when any server response get invalid due invalid params passed.
        8. unknownError: Calls on unknown error.
                                                                    
                                                                        Sample Code: 
                                                                        @Override
                                                                        public void someUIErrorOccurred(String inErrorMessage) {
                                                                        Toast.makeText(this, inErrorMessage, Toast.LENGTH_SHORT).show();
                                                                        }
                                                                        
                                                                        @Override
                                                                        public void onTransactionResponse(Bundle inResponse) {
                                                                        Toast.makeText(this, inResponse.toString(), Toast.LENGTH_SHORT).show();
                                                                        }
                                                                        
                                                                        @Override
                                                                        public void networkError() {
                                                                        Toast.makeText(this, "Network error", Toast.LENGTH_SHORT).show();
                                                                        }
                                                                        
                                                                        @Override
                                                                        public void clientAuthenticationFailed(String inErrorMessage) {
                                                                        Toast.makeText(this, inErrorMessage, Toast.LENGTH_SHORT).show();
                                                                        }
                                                                        
                                                                        @Override
                                                                        public void onErrorLoadingWebPage(int iniErrorCode, String inErrorMessage, String inFailingUrl) {
                                                                        Toast.makeText(this, inErrorMessage, Toast.LENGTH_SHORT).show();
                                                                        }
                                                                        
                                                                        @Override
                                                                        public void onBackPressedCancelTransaction() {
                                                                        Toast.makeText(this, "Back press cancel", Toast.LENGTH_SHORT).show();
                                                                        }
                                                                    
                                                                
  • Checksumhash ensures integrity of the request and is generated using the secret merchant key. Checksum is always generated on merchant server (where merchant key is placed) and then is passed to client or directly to Paytm depending on the flow. Server side utility code for generating checksumhash in popular development languages is available here. Checksum must include all parameters i.e. all the mandatory and optional parameters which have been received or is being posted.

    If Merchant code is in Java then merchant should pass TreeMap of all the parameters (parameter name would be key of TreeMap) to checksum utility method along with key to generate CHECKSUMHASH

                                                
                                                    CheckSumServiceHelper checksumHelper =CheckSumServiceHelper.getCheckSumServiceHelper();
                                                    String checksum = checksumHelper.genrateCheckSum(key,paramMap); // Key : Merchant Key, map : TreeMap of request parameters
                                                
                                            
  • Merchant Staging Credentials

    MID, Merchant Key, Industry type id, Channel id, Client Id, Client secret

    Staging payment instrument details

    Staging credentials are provided after document and platform verification

    Production credentials are provided after merchant has signed the agreement & complying to integration checklist on staging environment

    Staging CC/DC Credentials

    • Card Number -: Any valid VISA or MASTER card number
    • Expiry Date-: Any future date from transaction date
    • CVV-: Any three digit number
    • OTP-: 123123 (To test successful transaction)

    Staging Wallet Credentials:

    • Mobile Number – 7777777777
    • Password – Paytm12345
    • OTP – 489871
    • After every 5 minutes, the Wallet balance is topped up to Rs. 7,000

    Note: Netbanking, UPI and EMI cannot be currently tested in staging environment.