• Getting Started
    • Website Integration
      Mobile Integration (Android/IOS)
      Enterprise Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Webhooks
      Testing
      Refunds
      Guides
      Other Processes

      Initiate Transaction API

      Checksum required: Yes

      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 format: JSON

      Head

      ATTRIBUTEDESCRIPTIONMANDATORY
      version StringVersion of the API. Current version is v1.No
      channelId String (APP, WEB, WAP, SYSTEM)Channel through which call is initiated.
      For websites, the value is WEB
      For Mobile websites/App, the value is WAP.
      No
      requestTimestamp StringUNIX timestamp of the time request is being sent.No
      clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11.No
      signature StringChecksum string created by using paytm checksum llibrary.Yes

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      requestType StringThis parameter is used to identify the transaction flow. Value for custom checkout is 'Payment’ and for intelligent router is ‘UNI_PAY'.Yes
      mid StringThis is a unique identifier provided to every merchant by Paytm.Yes
      orderId StringUnique reference ID for a transaction which is generated by merchant and sent in the request.Paytm will reject the duplicate order request . No special character allowed except (“-”,”_”).Yes
      websiteName StringThis is provided by Paytm and it defines the static response URL.Yes
      txnAmount MoneyTransaction amount and the currency type.Yes
      userInfo UserInfoUser information contains user details like merchant customer ID, email, phone number etc.Yes
      paytmSsoToken StringPaytm Token for a user. This will not be available for merchants outside Paytm ecosystem.No
      enablePaymentMode PaymentMode arrayList of the payment modes which needs to enable. If the value provided then only listed payment modes are available for transaction.No
      disablePaymentMode PaymentMode arrayList of the payment modes which need to disable. If the value provided then all the listed payment modes are unavailable for transaction.No
      promoCode StringPromo code need to apply during transaction.No
      callbackUrl StringDynamic response url, if this value is provided then on completing the transaction, Paytm payment gateway will send the response on this URL. Sample URL is - https://merchant.com/callback/No
      goods GoodsInfo arrayThis contain the goods info for an order.No
      shippingInfo ShippingInfo arrayThis contain the shipping info for an order.No
      extendInfoExtendInfoMerchant can pass any order specific information that is required to be passed here.No
      paymentOffersApplied StringIn case of Offers based on Payment Instrument, inputs could be: paymentOffer parameter json string received in response of ApplyPromo API.No
      emiSubventionTokenStringGet emiSubventionToken from EMI Subvention - Validate API
      (Only for EMI - Subvention)
      No
      payableAmount MoneyGet finalTransactionAmount from EMI Subvention - Validate API and the currency type.
      (Only for EMI - Subvention)
      No

      Response Attributes

      Head

      ATTRIBUTEDESCRIPTIONMANDATORY
      version StringVersion of the API passed in the request.No
      responseTimestamp StringTimestamp at which response was sentYes
      clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11No
      signature StringChecksum string created by using paytm checksum llibrary.Yes

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      resultInfo ResultInfoResult InfoYes
      txnToken StringPaytm security token for a transaction valid for either one transaction or for 15 minutes. All subsequent API calls in creation will require this token.No
      isPromoCodeValid BooleanWhether promo code provided in request is Valid or not.Yes
      extraParamsMap Map<String, Object>Map for any extra information (in case of error).No
      authenticated BooleanTrue when ssoToken is provided in request and it is valid.No

      ExtendInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      udf1 StringUser define parameter 1No
      udf2 StringUser define parameter 2No
      udf3 StringUser define parameter 3No
      mercUnqRef StringUser define parameter 4No
      comments StringCommentsNo

      GoodsInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      merchantGoodsId StringUnique id for the goods item (item no)Yes
      merchantShippingId StringShipping IdNo
      snapshotUrl StringProduct Image URLNo
      description StringDescription of productYes
      category StringCategory of ProductYes
      quantity StringQuantity orderedYes
      unit StringUnit of quantity (KG/Litre)No
      price MoneyPrice of productYes
      extendInfo ExtendInfoExtended info of goodsNo

      PaymentMode

      ATTRIBUTEDESCRIPTIONMANDATORY
      modeString Mode of Payment:
      1. PAYTM_DIGITAL_CREDIT: paytm postpaid
      2. CREDIT_CARD: credit card
      3. DEBIT_CARD: debit card
      4. NET_BANKING: net banking
      5. UPI: BHIM UPI
      6. PPBL: paytm payments bank
      7. BALANCE: paytm wallet
      8. EMI: emi options
      No
      channelsarrayChannel associated with mode like:
      1. CREDIT_CARD/ DEBIT_CARD: VISA MASTER
      2. NET_BANKING: SBI,PNB,HDFC,ICICI
      No

      ShippingInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      merchantShippingId StringMerchant shipping idYes
      trackingNo StringTracking no of shipmentNo
      carrier StringShipping carrier nameNo
      chargeAmount MoneyShipping amountNo
      countryName StringShipping country nameYes
      stateName StringShipping stateYes
      cityName StringShipping cityYes
      address1 StringShipping address 1Yes
      address2 StringShipping address 2No
      firstName StringReceiver first nameYes
      lastName StringReceiver last nameYes
      mobileNo StringReceiver mobile noNo
      zipCode StringReceiver zip codeYes
      email StringReceiver emailNo

      UserInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      custId StringUnique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .Yes
      mobile String10-digit mobile number of userNo
      email StringValid email of the userNo
      firstName StringFirst name of the userNo
      lastName StringLast name of the userNo

      Money

      ATTRIBUTEDESCRIPTIONMANDATORY
      currency String (INR)currencyYes
      value String (regexp = [0-9]+([.][0-9]{1, 2})?, length less than 16 characters)txn amountYes

      ResultInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      resultCode StringResult code returned to merchant . Max length of result code can be 64Yes
      resultStatus StringStatus of API call
      (S:Success, F:Failure, U:Unknown)
      Yes
      resultMsg StringResult Message contains information about the result.Yes

      Response Codes and Messages

      resultCoderesultStatusresultMsg
      0000Ssuccessful operation
      0002SSuccess Idempotent
      1007FMissing mandatory element
      1008FPipe character is not allowed
      2004FSSO Token is invalid
      2007FTxn amount is invalid
      2009FDuplicate request, with same orderId is already in progres
      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
      00000900USystem error

      Endpoints

      Staging: https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id}

      Production: https://securegw.paytm.in/theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id}

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id}' --header 'Content-Type: application/json' --data '{"body":{"requestType":"{request-type}","mid":"{mid}","orderId":"{order-id}","websiteName":"{website-name}","txnAmount":{"value":"{transaction-amount-value}","currency":"{transaction-amount-currency}"},"userInfo":{"custId":"{customer-id}"},"callbackUrl":"{callback-url}"},"head":{"signature":"{signature}"}}'