• Getting Started
    • Mobile Integration (Android/IOS)
      Enterprise Solutions
      Retail Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Testing
      Refunds
      Guides
      Other Processes
      Mini Program Platform

      post Initiate Transaction API

      Use Case


      To start transaction for native flow, merchant need to first call this api and this api will return the txn Token which will be used in all the other native APIs.

      Request Attributes


      API Content Type: JSON

      Head1

      Head

      ATTRIBUTEDESCRIPTION
      version string(4)
      optional
      Version of the API.
      Example: v1
      channelId string(3)
      optional
      The parameter value identifies the Channel for which API call is initiated.
      Possible Values: WEBFor websites, the value to be passed should be "WEB", WAPFor Mobile websites/App, the value to be passed should be "WAP"
      requestTimestamp string(15)
      optional
      EPOCH timestamp of the time at which request is being sent.
      Example: 1588402269
      clientId string(3)
      optional
      Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.
      Example: C11
      signature string(108)
      mandatory
      Paytm validates the parameter values by verifying the signature comes in the request. It ensures that parameter values are not tempered. Signature string can be created by using Paytm checksum library
      Body1

      Body

      ATTRIBUTEDESCRIPTION
      requestType string(30)
      mandatory
      This parameter is used to identify the transaction flow.
      Possible Values: PaymentFor Custom Checkout, UNI_PAYFor Intelligent Router
      mid string(20)
      mandatory
      Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.
      Example: INTEGR7769XXXXXX9383
      orderId string(50)
      mandatory
      The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”.
      Example: OREDRID_98765
      websiteName string(30)
      mandatory
      This is provided by Paytm and it defines the static response URL.
      Example: WEBSTAGING, DEFAULT
      Note: other websiteName provided by paytm
      txnAmount object
      mandatory
      This parameter is an object and should contain the value of transaction i.e. amount and currency type
      Example: {"value" : "1.00", "currency" : "INR"}
      TxnAmount +
      AttributeDescription
      value string
      mandatory
      This parameter contains the amount to be charged to the customer and can have two places of decimal.
      Example: 1.00
      currency string(INR)
      mandatory
      This parameter indicates the currency in which transaction amount is to be deducted.
      Possible Values: INR
      userInfo object
      mandatory
      User information contains user details like customer ID, email, phone number etc.
      UserInfo +
      AttributeDescription
      custId string(32)
      mandatory
      Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .
      Example: CUST_001
      mobile string(10)
      optional
      10-digit mobile number of user
      Example: 7777777777
      email string(32)
      optional
      Valid email of the user
      firstName string(32)
      optional
      First name of the user
      lastName string(32)
      optional
      Last name of the user
      paytmSsoToken string(30)
      optional
      This is a unique token linked with user's Paytm wallet and is provided in the response while linking user's Paytm wallet.
      Example: ae74f8b5-be5f-4503-XXXX-a60c9dcd3300
      enablePaymentMode array of object
      optional
      List of the payment modes which needs to enable. If the value provided then only listed payment modes are available for transaction.
      Example: [{"mode" : "UPI", "channels" : ["UPIPUSH"]}]
      PaymentMode +
      AttributeDescription
      mode string(15)
      optional
      Mode of Payment
      Possible Values: BALANCE For Paytm Wallet, PPBLFor Paytm Payments Bank, UPIFor Bhim Upi, CREDIT_CARDFor Credit Card, DEBIT_CARDFor Debit Card, NET_BANKINGFor Net Banking, EMIFor Emi Options, PAYTM_DIGITAL_CREDITFor paytm postpaid
      channels array
      optional
      Channel associated with mode
      Possible Values:
      For UPI: UPIFor UPI Collect , UPIPUSH For UPI Push , UPIPUSHEXPRESS For UPI Intent
      For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
      For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
      disablePaymentMode array of object
      optional
      List of the payment modes which need to disable. If the value provided then all the listed payment modes are unavailable for transaction.
      Example: [{"mode" : "UPI", "channels" : ["UPIPUSH"]}]
      PaymentMode +
      AttributeDescription
      mode string(15)
      optional
      Mode of Payment
      Possible Values: BALANCE For Paytm Wallet, PPBLFor Paytm Payments Bank, UPIFor Bhim Upi, CREDIT_CARDFor Credit Card, DEBIT_CARDFor Debit Card, NET_BANKINGFor Net Banking, EMIFor Emi Options, PAYTM_DIGITAL_CREDITFor paytm postpaid
      channels array
      optional
      Channel associated with mode
      Possible Values:
      For UPI: UPIFor UPI Collect , UPIPUSH For UPI Push , UPIPUSHEXPRESS For UPI Intent
      For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
      For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
      promoCode string
      optional
      It is the code that has been applied during the transaction on the merchant website
      Example: TESXXXOMO
      callbackUrl string(255)
      optional
      Paytm sends the response of transaction on the URL which comes in the callbackUrl parameter.
      Example: https://merchant.com/callback/
      goods array of object
      optional
      This contain the goods info for an order.
      GoodsInfo +
      AttributeDescription
      merchantGoodsId string
      optional
      Unique id for the goods item (item no)
      merchantShippingId string
      optional
      Shipping Id
      snapshotUrl string
      optional
      Product Image URL
      description string
      mandatory
      Description of product
      category string
      optional
      Category of Product
      quantity string
      mandatory
      Quantity ordered
      unit string
      optional
      Unit of quantity (KG/Litre)
      price object
      mandatory
      Price of product
      Money +
      AttributeDescription
      value string
      mandatory
      This parameter contains the amount to be charged to the customer and can have two places of decimal.
      Example: 1.00
      currency string
      mandatory
      This parameter indicates the currency in which transaction amount is to be deducted.
      Possible Values: INR
      extendInfo object
      optional
      Extended info of goods
      ExtendInfo +
      AttributeDescription
      udf1 string(64)
      optional
      User define parameter 1
      udf2 string(64)
      optional
      User define parameter 2
      udf3 string(64)
      optional
      User define parameter 3
      mercUnqRef string(64)
      optional
      Merchant's reference text which comes in final response of Process Transaction API from Paytm
      comments string(256)
      optional
      Comments
      shippingInfo array of object
      optional
      This contain the shipping info for an order.
      ShippingInfo +
      AttributeDescription
      merchantShippingId string
      optional
      Merchant shipping id
      trackingNo string
      optional
      Tracking no of shipment
      carrier string
      optional
      Shipping carrier name
      chargeAmount object
      mandatory
      Shipping amount
      Money +
      AttributeDescription
      value string
      mandatory
      This parameter contains the amount to be charged to the customer and can have two places of decimal.
      Example: 1.00
      currency string
      mandatory
      This parameter indicates the currency in which transaction amount is to be deducted.
      Possible Values: INR
      countryName string
      optional
      Shipping country name
      stateName string
      optional
      Shipping state name
      cityName string
      optional
      Shipping city name
      address1 string
      optional
      Shipping address 1
      address2 string
      optional
      Shipping address 2
      firstName string
      optional
      Receiver first name
      lastName string
      optional
      Receiver last name
      mobileNo string
      optional
      Receiver mobile no
      zipCode string
      optional
      Receiver zip code
      email string
      optional
      Receiver email
      extendInfo object
      optional
      Merchant can pass any order specific information that is required to be passed here.
      ExtendInfo +
      AttributeDescription
      udf1 string(64)
      optional
      User define parameter 1
      udf2 string(64)
      optional
      User define parameter 2
      udf3 string(64)
      optional
      User define parameter 3
      mercUnqRef string(64)
      optional
      Merchant's reference text which comes in final response of Process Transaction API from Paytm
      comments string(256)
      optional
      Comments
      paymentOffersApplied object
      optional
      In case of Offers based on Payment Instrument, inputs could be: paymentOffer parameter json string received in response of ApplyPromo API.
      Either paymentOffersApplied or simplifiedPaymentOffers.
      To be used for integration method 1 flow.
      Example: {"totalInstantDiscount":"25.00","totalCashbackAmount":null,"offerBreakup":[{"promocodeApplied":"HDFCCC","promotext":"Promocode applied successfully","instantDiscount":"25.00","cashbackAmount":null,"payMethod":"CREDIT_CARD","promoVisibility":"false","responseCode":null125;]}
      simplifiedPaymentOffers object
      conditional
      Object of Simplified Payment Offers.
      Either paymentOffersApplied or simplifiedPaymentOffers. To be used for integration method 2 flow.
      Example: { "promoCode":"TESTXXWALLET","applyAvailablePromo":"true","validatePromo":"false" }
      SimplifiedPaymentOffers +
      AttributeDescription
      promoCode string
      optional
      Set promocode
      Example: TESTXXWALLET
      applyAvailablePromo string
      optional
      Default Promo to be applied.
      Possible Values: true, false
      Default: true
      validatePromo string
      optional
      To validate Promo to be applied and fail transaction accordingly.
      Possible Values: true, false
      Default: false
      emiSubventionToken string
      optional
      Get emiSubventionToken from EMI Subvention - Validate API (Only for EMI - Subvention)
      Example: a18fa0d896444b18a237d5XXXXdbc79e1576762049265
      payableAmount object
      optional
      Get finalTransactionAmount from EMI Subvention - Validate API and the currency type. (Only for EMI - Subvention)
      Money +
      AttributeDescription
      value string
      mandatory
      This parameter contains the amount to be charged to the customer and can have two places of decimal.
      Example: 1.00
      currency string(INR)
      mandatory
      This parameter indicates the currency in which transaction amount is to be deducted.
      Possible Values: INR

      Response Attributes


      API Content Type: JSON

      Head2

      Head

      ATTRIBUTEDESCRIPTION
      version string(2)
      Version of the API passed in the request.
      Example: v1
      responseTimestamp string(15)
      EPOCH timestamp of the time at which response is being sent.
      Example: 1588402269
      clientId string(3)
      Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.
      Example: C11
      signature string(108)
      You should validate the parameter values by verifying the signature comes in the response. It ensures that parameter values not tempered. Signature string can be verified by using Paytm checksum library
      Body2

      Body

      ATTRIBUTEDESCRIPTION
      resultInfo object
      This parameter gives the information about the result of the API response
      ResultInfo +
      AttributeDescription
      resultCode string
      This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below
      resultStatus string
      This parameter indicates the status of API call.
      Possible Values: SFor Success, FFor Failure, UFor Unknown
      resultMsg string(256)
      This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below
      isRedirect boolean
      This flag indicates that number of retries are over and user is to be redirected from cashier page
      bankRetry boolean
      This flag indicates that retry is allowed at bank's end or not
      retry boolean
      This flag indicates whether retry is allowed or not
      txnToken string(64)
      Unique Transaction Token generated in reponse of the this API. It is valid for 15 minutes and merchant has to send back the same transaction token everytime in each subsequent API Call to communicate with PG.
      Example: f0bed899539742309eebd8XXXX7edcf61588842333227
      isPromoCodeValid boolean
      Whether promo code provided in request is Valid or not.
      extraParamsMap object
      Map for any extra information (in case of error).
      authenticated boolean
      True when ssoToken is provided in request and it is valid.

      Response Codes and Messages


      resultCoderesultStatusresultMsg
      0000SSuccess
      0002SSuccess Idempotent
      196FPayment failed as amount entered exceeds the allowed limit.
      Please enter a lower amount and try again or reach out to the merchant for further assistance.
      1006FYour Session has expired
      1007FMissing mandatory element
      1008FPipe character is not allowed
      1011FInvalid Promo Param
      1012FPromo amount cannot be more than transaction amount
      2004FSSO Token is invalid
      2005FChecksum provided is invalid
      2007FTxn amount is invalid
      2013FMid in the query param doesn’t match with the Mid sent in the request
      2014FOrderId in the query param doesn’t match with the OrderId sent in the request
      2023FRepeat Request Inconsistent
      00000900USystem error
      StagingProduction
      REQUESTRESPONSE
      curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid={mid}&orderId=ORDERID_98765' \
      --header 'Content-Type: application/json' \
      --data '{"body":{"requestType":"Payment","mid":"{mid}","websiteName":"WEBSTAGING","orderId":"ORDERID_98765","txnAmount":{"value":"1.00","currency":"INR"},"userInfo":{"custId":"CUST_001"},"callbackUrl":"https://merchant.com/callback"},"head":{"signature":"{signature}"}}'