search

POSTInitiate 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

Content Type : JSON

Head

AttributeDescription
version
string
optional

Version of the API.

Example: v1

channelId
string
optional

The parameter value identifies the Channel for which API call is initiated.

Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
requestTimestamp
string
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

clientId
string
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
mandatory

Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.

Body

AttributeDescription
requestType
string
mandatory

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

Possible Values:
Payment
For Custom Checkout
,
UNI_PAY
For Intelligent Router
mid
string
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
mandatory

The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”.
Example: OREDRID_98765

websiteName
string
mandatory

This is provided by Paytm and it defines the static response URL.
Example: WEBSTAGING, DEFAULT
Note: other websiteName provided by paytm

txnAmount
string
optional

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
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

userInfo
string
optional

User information contains user details like customer ID, email, phone number etc.

UserInfo +
AttributeDescription
custId
string
mandatory

Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .
Example: CUST_001

mobile
string
optional

10-digit mobile number of user.
Example: 9988000000

email
string
optional

Valid email of the user.

Example: vaibhav41094@gmail.com

firstName
string
optional

First name of the user

lastName
string
optional

Last name of the user.

paytmSsoToken
string
optional

This is a unique token linked with user's Paytm wallet and is provided in the response while linking user's Paytm wallet.

enablePaymentMode
string
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
optional
Mode of Payment
BALANCE,
For Paytm Wallet
PPBL, UPI,
For Paytm Payments Bank
CREDIT_CARD
For Credit Card
DEBIT_CARD
For Debit Card
NET_BANKING
For Net Banking
EMI
For Emi Options
PAYTM_DIGITAL_CREDIT
For paytm postpaid
channels
array
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For 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 objects
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
optional
Mode of Payment
BALANCE,
For Paytm Wallet
PPBL, UPI,
For Paytm Payments Bank
CREDIT_CARD
For Credit Card
DEBIT_CARD
For Debit Card
NET_BANKING
For Net Banking
EMI
For Emi Options
PAYTM_DIGITAL_CREDIT
For paytm postpaid
channels
array
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For 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
optional

Paytm sends the response of transaction on the URL which comes in the callbackUrl parameter.

Example: https://merchant.com/callback/

goods
array of objects
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

Merchant shipping id

snapshotUrl
string
optional

Product Image URL

description
string
optional

Description of product

category
string
optional

Category of Product

quantity
string
optional

Quantity ordered

unit
string
optional

Unit of quantity (KG/Litre)

price
string
optional

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
string
optional

Extended info of goods

ExtendedInfo +
AttributeDescription
udf1
string
optional

User define parameter 1

udf2
string
optional

User define parameter 2

udf3
string
optional

User define parameter 3

merUnqRef
string
optional

Merchant's reference text which comes in final response of Process Transaction API from Paytm

comments
string
optional

Comments

shippingInfo
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
string
optional

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

Valid email of the user.

Example: vaibhav41094@gmail.com

extendInfo
object
optional

Merchant can pass any order specific information that is required to be passed here.

ExtendedInfo +
AttributeDescription
udf1
string
optional

User define parameter 1

udf2
string
optional

User define parameter 2

udf3
string
optional

User define parameter 3

merUnqRef
string
optional

Merchant's reference text which comes in final response of Process Transaction API from Paytm

comments
string
optional

Comments

paymentOffersApplied
string
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 cuctom checkout-type 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
optional

Object of Simplified Payment Offers.
Either paymentOffersApplied or simplifiedPaymentOffers. To be used for custom checkout-type 2JS checkout and all-in-one SDK flows.

Example: { "promoCode":"TESTXXWALLET","applyAvailablePromo":"true","validatePromo":"false" }

simplifiedPaymentOffers +
AttributeDescription
promoCode
string
optional

It is the code that has been applied during the transaction on the merchant website.
Example: TESXXXOMO

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
string
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
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string

Version of the API passed in the request.
Example: v1

responseTimestamp
string

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

clientId
string

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

signature
string

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.

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:
S,
For Success
F,
For Failure
U
For Unknown
resultMsg
string

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 that retry is allowed at bank's end or not.

txnToken
string

This is the unique transaction token received in the response of Initiate Transaction API. It is valid for 15 minutes.

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 & 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
Staging
Production
https://securegw-stage.paytm.in/theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
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}"}}'  
copy icon