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

      post Apply Promo API

      Use Case


      To apply the promotion/offer selected by the user for particular transaction.

      Request Attributes


      API Content Type: JSON

      Head1

      Head

      ATTRIBUTEDESCRIPTION
      requestId string
      optional
      Unique reference ID for a transaction which is generated by merchant.
      requestTimestamp string(15)
      optional
      EPOCH timestamp of the time at which request is being sent.
      Example: 1588402269
      version string(4)
      optional
      Version of the API.
      Example: v1
      channelId string(3)
      mandatory
      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"
      tokenType string
      mandatory
      This is for authentication method.
      For SSO token authentication, the value is SSO.
      For checksum authentication, the value is CHECKSUM.
      token string
      mandatory
      In case of tokenType SSO Inputs could be : SSO token value.
      In case of tokenType CHECKSUM Inputs could be : CHECKSUM value.
      Body1

      Body

      ATTRIBUTEDESCRIPTION
      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
      custId string
      optional
      Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .
      promoCode string
      optional
      Title of promocode,if blank Paytm will apply best offer on that merchant.
      paymentOptions PaymentOptions
      mandatory
      In case of hybrid it will have multiple objects.
      PaymentOptions +
      AttributeDescription
      transactionAmount string
      mandatory
      Amount in rupees.
      payMethod string
      mandatory
      Name of Payment Method. Possible values are: BALANCE, BANK_EXPRESS, NET_BANKING, CREDIT_CARD, DEBIT_CARD,IMPS,ATM, EMI, COD, MP_COD, HYBRID_PAYMENT, UPI, PAYTM_DIGITAL_CREDIT, PREPAID_CARD, PPBL,LOYALTY_POINT, REFUND_MANUAL, EMI_DC, WALLET
      bankCode string
      optional
      Code of the bank provided here.
      cardNo string
      optional
      Card number present on your Debit/Credit card.
      savedCardId string
      optional
      Paytm saved card Id unique for each card.
      vpa string
      optional
      This is needed for UPI transaction.
      totalTransactionAmount string
      mandatory
      Sum of all the transaction amount in paymentOptions, in rupees.

      Note: In case of hybrid only non wallet amount and details should be sent.

      Response Attributes


      API Content Type: JSON

      Head2

      Head

      ATTRIBUTEDESCRIPTION
      requestId string
      Unique reference ID for a transaction which is generated by merchant.
      responseTimestamp string(15)
      EPOCH timestamp of the time at which response is being sent.
      Example: 1588402269
      version string(2)
      Version of the API passed in the request.
      Example: v1
      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
      resultCodeId string
      Result code id returned to merchant.
      resultStatus string
      This parameter indicates the status of API call.
      Possible Values: SFor Success, FFor Failure
      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
      paymentOffers PaymentOffer
      Detail of payment offer.
      PaymentOffer +
      AttributeDescription
      totalInstantDiscount Numeric string
      Sum of instant discounts on all paymethod(Wallet+Other in case of hybrid) in rupees.
      totalCashbackAmount Numeric string
      Sum of cashbacks on all paymethod(Wallet+Other in case of hybrid) in rupees.
      offerBreakup object
      Detail of offer being applied.
      OfferBreakup +
      AttributeDescription
      promocodeApplied string
      Promocode applied by the user.
      promotext string
      Text message for promocode.
      promoVisibility string
      Based on this flag frontend will show error message.In success this will be false.
      responseCode string
      This will used by external merchants to display user messages for promo.
      instantDiscount Numeric string
      Amount in rupees
      cashbackAmount Numeric string
      Amount in rupees.
      payMethod string
      Name of payment method.
      Possible values are: BALANCE, BANK_EXPRESS, NET_BANKING, CREDIT_CARD, DEBIT_CARD,IMPS,ATM, EMI, COD, MP_COD, HYBRID_PAYMENT, UPI, PAYTM_DIGITAL_CREDIT, PREPAID_CARD, PPBL,LOYALTY_POINT, REFUND_MANUAL, EMI_DC, WALLET

      Note: If no offer is active on the merchant then Paytm will send an error response ( i.e. resultStatus = "F" ). If merchant has active offers but no offer is applicable on payment instrument supplied Paytm will send success response ( i.e. resultStatus = "S" ) with proper message in promo text.

      Response Codes and Messages


      resultCoderesultStatusresultMsg
      00000000SSuccess
      9999FSomething went wrong.
      1012FNo promo code currently active on the merchant.
      1001FRequest parameters are not valid.
      2005FChecksum provided is invalid.
      StagingProduction
      REQUESTRESPONSE
      curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/applyPromo?mid={mid}' \
      --header 'Content-Type: application/json' \
      --data '{"body":{"mid":"{mid}","custId": "CUST_001","paymentOptions":[{"transactionAmount":"100","payMethod":"CREDIT_CARD","bankCode":"HDFC","cardNo":"4111111111111111"}],"totalTransactionAmount":"100"},"head":{"channelId":"WEB","tokenType":"CHECKSUM","token":"{CHECKSUM}"}}'