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

PARAMETERDESCRIPTIONREQUIRED
version StringApplication version(provided by paytm)Yes
channelId String (APP, WEB, WAP, SYSTEM)Channel through which call initiatedYes
requestTimestamp StringUNIX timestamp of the time request is being sentNo
clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11Yes
signature StringChecksum string created by using paytm checksum logic/libraryYes

Body

PARAMETERDESCRIPTIONREQUIRED
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 StringMerchant unique identifier, Unique Id for merchant provided by paytmYes
orderId StringUnique order for each order request paytm will reject the duplicate order request No special character allowed except (“-”,”_”)Yes
websiteName StringThis is provided by Paytm define the static response urlYes
txnAmount MoneyTransaction amount and the currency valueYes
userInfo UserInfoUser information contains user detailsYes
paytmSsoToken StringPaytm Token for a userNo
enablePaymentMode PaymentMode arraylist of the payment modes which needs to enable. If the value provided then only listed payment modes are available for transactionNo
disablePaymentMode PaymentMode arraylist of the payment modes which need to disable. If the value provided then all the listed payment modes are unavailable for transactionNo
promoCode StringPromo code need to apply during transactionNo
callbackUrl StringDynamic response url, if this value is provided then on completing the transaction response send on this urlNo
goods GoodsInfo arrayThis contain the goods info for an orderNo
shippingInfo ShippingInfo arrayExtended info of goodsNo
extendInfo ExtendInfoThis contain the set of parameters for some additional informationNo

Response Attributes

Head

PARAMETERDESCRIPTIONREQUIRED
version StringApplication versionYes
responseTimestamp StringTimestamp at which response was sentYes
clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11Yes
signature StringChecksum string created by using paytm checksum logic/libraryYes

Body

PARAMETERDESCRIPTIONREQUIRED
resultInfo ResultInfoResult InfoYes
txnToken StringtxnToken paytm security token for a transaction valid for the 15 minutesNo
promoCodeValid BooleanWhether promo code provided in request is Valid or notYes
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 validNo

ExtendInfo

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

GoodsInfo

PARAMETERDESCRIPTIONREQUIRED
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/Liter)No
price MoneyPrice of productYes
extendInfo ExtendInfoExtended info of goodsNo

PaymentMode

PARAMETERDESCRIPTIONREQUIRED
modeString arrayMode 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
channelsString arrayChannel associated with mode like:
  1. CREDIT_CARD/ DEBIT_CARD: VISA MASTER
  2. NET_BANKING: SBI,PNB,HDFC,ICICI
No

ShippingInfo

PARAMETERDESCRIPTIONREQUIRED
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

PARAMETERDESCRIPTIONREQUIRED
custId Stringuser unique identification no provided byYes
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

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

ResultInfo

PARAMETERDESCRIPTIONREQUIRED
resultStatus StringStatus of API callYes
resultCode StringResult code returned to merchant . Max length of result code can be 64Yes
resultMsg StringResult Message contains information about the result.Yes

Responses

RESPONSE CODEDESCRIPTION
0000successful operation
0002Success Idempotent
00000900System error
1007Missing mandatory element
1008Pipe character is not allowed
2004SSO Token is invalid
2007Txn amount is invalid
2009Duplicate request, with same orderId is already in progres
2013Mid in the query param doesn’t match with the Mid send in the request
2014OrderId in the query param doesn’t match with the OrderId send in the request

Endpoints

Testing: https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid=<mid>&orderId=<orderId>

Production: https://securegw.paytm.in/theia/api/v1/initiateTransaction?mid=<mid>&orderId=<orderId>

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid=TIMESI54326042593468&orderId=ORDER_1555169231' --header 'Content-Type: application/json' --data '{"body":{"requestType":"Payment","mid":"TIMESI54326042593468","websiteName":"dineoutWEB","orderId":"ORDER_1555169231","txnAmount":{"value":"100.00","currency":"INR"},"userInfo":{"custId":"CUST001"},"callbackUrl":"https://pg-stage.paytm.in/MerchantSite/bankResponse"},"head":{"clientId":"C11","version":"v1","requestTimestamp":1555169231,"channelId":"WEB","signature":"EDRDpWf+E9S6QvMhO3y6K7dkFU5qnpY/6RziUYbH7XRj6XZfKpumkmamEL2P+w2iv7w2ZV0P1iaIlcOSnGovePa3rK7DBYa8a17nt4C4rT8="}}'