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

      Apply Promo API

      Checksum required: Yes

      Use Case


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

      Request Attributes

      API Content format: Application/JSON


      Head

      ATTRIBUTEDESCRIPTIONMANDATORY
      requestIdStringUnique reference ID for a transaction which is generated by merchant.No
      requestTimestampStringUNIX timestamp of the time request is being sent.No
      channelIdStringChannel through which call is initiated.
      For websites, the value is WEB.
      For Mobile websites/App, the value is WAP.
      Yes
      versionStringVersion of the API. Current version is v1.No
      tokenTypeStringThis is for authentication method.
      For SSO token authentication, the value is SSO.
      For checksum authentication, the value is CHECKSUM.
      Yes
      tokenStringIn case of tokenType SSO Inputs could be : SSO token value.
      In case of tokenType CHECKSUM Inputs could be : CHECKSUM value.
      Yes

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      mid StringThis is a unique identifier provided to every merchant by Paytm.Yes
      custId StringUnique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .No
      promocode StringTitle of promocode,if blank Paytm will apply best offer on that merchant.No
      paymentOptions PaymentOptions In case of hybrid it will have multiple objects.Yes
      totalTransactionAmount StringSum of all the transaction amount in paymentOptions, in rupees.Yes

      PaymentOptions

      ATTRIBUTEDESCRIPTIONMANDATORY
      transactionAmount Numeric StringAmount in rupees.Yes
      payMethod Enum StringsName 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
      Yes
      bankCode StringCode of the bank provided here.No
      cardNo StringCard number present on your Debit/Credit card.No
      savedCardId StringPaytm saved card Id unique for each card.No
      vpa StringThis is needed for UPI transaction.No
      Note: In case of hybrid only non wallet amount and details should be sent.

      Response Attributes


      Head

      ATTRIBUTEDESCRIPTION
      requestId StringUnique reference ID for a transaction which is generated by merchant sent in request.
      responseTimestamp StringUNIX Timestamp of the response.
      version StringVersion of the API passed in the request.

      Body

      ATTRIBUTEDESCRIPTION
      paymentOffers PaymentOfferDetail of payment offer.
      resultInfo ResultInformation related to response of the request.

      PaymentOffer

      ATTRIBUTEDESCRIPTION
      totalInstantDiscount Numeric StringSum of instant discounts on all paymethod(Wallet+Other in case of hybrid) in rupees.
      totalCashbackAmount Numeric StringSum of cashbacks on all paymethod(Wallet+Other in case of hybrid) in rupees.
      offerBreakup OfferBreakupDetail of offer being applied.


      OfferBreakup

      ATTRIBUTEDESCRIPTION
      promocodeApplied StringPromocode applied by the user.
      promotext StringText message for promocode.
      promoVisibility Enum StringBased on this flag frontend will show error message.In success this will be false.
      responseCode StringThis will used by external merchants to display user messages for promo.
      instantDiscount Numeric StringAmount in rupees.
      cashbackAmount Numeric StringAmount in rupees.
      payMethod Enum StringsName 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

      Result

      ATTRIBUTEDESCRIPTION
      resultCode String (5)Result code returned to merchant.
      resultCodeId String (5)Result code id returned to merchant.
      resultStatus String (10)Status of API call (Success/Failure)
      (S:Success, F:Failure, U:Unknown)
      resultMsg String (256)Result Message contains information about the result.
      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.

      Endpoints

      Staging: https://securegw-stage.paytm.in/theia/api/v1/applyPromo?mid={mid}

      Production: https://securegw.paytm.in/theia/api/v1/applyPromo?mid={mid}

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/applyPromo?mid={mid}' --header 'Content-Type: application/json' --data '{"body": {"mid": "{mid}","custId": "{customer-id}","paymentOptions": [{"transactionAmount": "{amount}","payMethod": "{pay-mode}","bankCode": "{bank-code}","cardNo": "{card-no}"}],"totalTransactionAmount": "100"},"head": {"channelId": "WEB","tokenType":"CHECKSUM","token": "{CHECKSUM}"}}'