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
conditional

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"
Note: It is Mandatory in case of Bank Offer.
requestTimestamp
string
optional

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

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

This parameter is used to identify the transaction flow.

Possible Values: 'Payment' for 'One time Payment' for all checkout flows

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 max length is 50 characters.

Example: OREDRID_98765

callbackUrl
string
conditional

Paytm sends the response of transaction on the URL which comes in the callbackUrl parameter. If this param is not present then websiteName param key will be used to get the static callbackUrl.
Example: https://<callback URL to be used by merchant>
Note: Either of websiteName or callbackUrl should be passed in the request.

websiteName
string
mandatory

websiteName is the key to extract the static callbackUrl defined for merchant at Paytm. This is provided by Paytm.

Possible Values:

WEBSTAGING
For Staging/Integration environment
,
DEFAULT
For Production environment

Note: URL passed in callbackUrl has a higher preference over the URL configured against this key.

txnAmount
object
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
object
mandatory
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
conditional

10-digit mobile number of user.
Example: 9988000000

Mandatory, in case merchant wants to give Debit Card EMI as a payment option to its users.

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
array of objects
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 of strings
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For UPI Collect
UPIPUSH
For UPI Intent
UPIPUSHEXPRESS
For UPI Push

For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
banks
Array of strings
optional

Different Banks are available
"ICICI", "SBI", "AXIS".  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 of strings
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For UPI Collect
UPIPUSH
For UPI Intent
UPIPUSHEXPRESS
For UPI Push

For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
banks
Array of strings
optional

Different Banks are available
"ICICI", "SBI", "AXIS".  List of banks

promoCode
string
optional

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

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
mandatory

Description of product

category
string
optional

Category of Product

quantity
string
mandatory

Quantity ordered

unit
string
optional

Unit of quantity (KG/Litre)

price
object
mandatory

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

Extended info of goods

ExtendedInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

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

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

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
object
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.

extendInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

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

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

VanInfo
object
optional

Details of customer VAN.

VanInfo
+
AttributeDescription
merchantPrefix
string(4)
mandatory

Merchant identifier issued to the merchant at the time of onboarding. Merchants can opt for names resembling their business names.

Example: Paytm can opt for merchant prefix as PYTM.

identificationNo
string(10)
conditional

This is 10 digits alphanumeric string that forms that last 10 digits of the VAN. While merchants can use this in multiple ways possible, this should be unique to the entity against which reconciliation is required. The length of this is fixed and hence needs to be accommodated for while passing this string.

purpose
string(256)
optional

The purpose for which VAN is getting created. This is free string that can be passed by merchant. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.

payableAmount
object
optional

Get finalTransactionAmount from EMI Subvention - Validate API/Apply Offer 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

splitSettlementInfo
object
optional

Split payment details

Note: Send only in case split settlement required
SplitSettlementInfo
+
AttributeDescription
splitType
string
optional

Possible values: AT_TXN / POST_TXN or blank, blank is also considered as AT_TXN with below split infos.

postTxnSplitTimeout
string
optional

Timeout in no. of calender days. Either leave it blank or pass 1 for same day timeout.

splitMethod
string
mandatory

Split method
Possible Values: AMOUNT, PERCENTAGE

splitInfo
Array
mandatory

List for child vendor merchant mid's and their split info

SplitInfo
+
AttributeDescription
mid
string
mandatory

Child mid

amount
object
conditional

Share of child vendor in the split by amount base
Use: Only splitMethod is AMOUNT

Amount
+
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

percentage
string
conditional

Share of child vendor in the split by percentage base
Use: Only splitMethod is PERCENTAGE

partnerId
string
conditional

Optional alternate id created for child MID

goods
object
optional

Split merchant goods info list

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
mandatory

Description of product

category
string
optional

Category of Product

quantity
string
mandatory

Quantity ordered

unit
string
optional

Unit of quantity (KG/Litre)

price
object
mandatory

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

Extended info of goods

ExtendedInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

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

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

shippingInfo
object
optional

Split merchant shipping info list

ShippingInfo
+
AttributeDescription
merchantShippingId
string
optional

Merchant shipping id

trackingNo
string
optional

Tracking no of shipment

carrier
string
optional

Shipping carrier name

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

Extended info of goods.

extendInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

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

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

unifiedOffersToken
string
conditional

Get unifiedOffersToken from Apply Offer API 

Example:a18fa0d896444b18a237d5XXXXdbc79e1576762049265

simplifiedUnifiedOffers
object
conditional

Object of Simplified Unified Offer to apply offers on a transaction.
Either simplifiedUnifiedOffers object or unifiedOffersToken will have to be passed in case of offer integration.

simplifiedUnifiedOffers
+
AttributeDescription
promoDetails
object
conditional

Object to be passed for applying bank offer

promoDetails
+
AttributeDescription
applyAvailablePromo
boolean
optional

Default Promo to be applied.
Possible Values: true, false
Default: true

validatePromo
boolean
optional

To validate Promo to be applied and fail transaction accordingly.
Possible Values: true, false
Default: false

isAmountBasedBankOffer
boolean
optional

To run amount based bank offer, send this as true. Else send this as false.

Possible Values: true, false

Default: true

offerId
string
conditional

It is the identifier for the offer that has been applied during the transaction on the merchant website.
Example: 2134516

promoAmount
Double
optional

The amount eligible for applying offer/promo. Can be used incase the offer has to be applied on partial transaction amount

subventionDetails
object
conditional

Object to be passed for applying EMI Subvention

subventionDetails
+
AttributeDescription
pgPlanId
string
optional

EMI plan id needs to be sent only in those cases where you either keep the plan ids data at your end or receive the same in any API response.

Example: ICICI|3

Note: This param need not be send for EMI subvention integration through All-in-one SDK or JS checkout

 

isAmountBasedSubvention
boolean
optional

To run amount based subvention send this as true. Else send this as false.

Possible Values: true, false

Default: true

subventionAmount
double
conditional

Amount on which subvention is to be applied for amount based validation (mandatory for amount based subvention).

offerId
string
conditional

OfferId that is enabled on the product (mandatory for amount based subvention).

items
object
optional

List of items

item
+
AttributeDescription
id
string
mandatory

Any unique identifier for one item in the request e.g. in case of 2 items in the cart, the values can be sent as 1234 and 1236.

productId
string
mandatory

Unique product identifier for the merchant.

brandId
string
mandatory

Product brand identifier for the merchant
Example: LG, Sony etc. Should be send in the request if EMI plans are configured with brand attribute.

categoryId
string
mandatory

Product category identifier for the merchant (categories can be Electronics, footwears etc). This should be sent in the request with same value which is configured in the EMI plan.

price
Integer
mandatory

Price of the product

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":"{websiteName}","orderId":"ORDERID_98765","txnAmount":{"value":"1.00","currency":"INR"},"userInfo":{"custId":"CUST_001"},"callbackUrl":"https://<callback URL to be used by merchant>"},"head":{"signature":"{signature}"}}'  
copy icon