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

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
conditional

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. Either of websiteName or callbackUrl should be passed in the request.

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
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
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
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 Intent
UPIPUSHEXPRESS
For UPI Push

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

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

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

simplifiedSubvention
object
optional

Object of Simplified subvention.
Either simplifiedSubvention object or emiSubventionToken will have to be passed in case of EMI subvention integration

SimplifiedSubvention
+
AttributeDescription
planId
string
conditional

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.
Note: This param need not be send for EMI subvention integration through All-in-one SDK or JS checkout

customerId
string
mandatory

Customer id

items
object
conditional

Items for subvention (mandatory for product based subvention)

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
optional

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

categoryList
string
mandatory

Product category identifiers 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.

model
string
optional

Model id of the product. This should be sent if the merchant's EMI plans are configured with model attribute.

ean
string
optional

(Bar code Number) of product. This should be sent if the merchant's EMI plans are configured with EAN attribute.

price
double
mandatory

Cumulative price of the product (multiplied by quantity)

quantity
int
mandatory

Quantity of the product.quantity

verticalId
string
mandatory

Merchant need to send this field with value "PAYTM_EMI"

isEmiEnabled
boolean
mandatory

Whether EMI is Enabled for the product.

offerDetails
object
mandatory

OfferId that is enabled on the product

OfferDetail
+
AttributeDescription
offerId
string
mandatory

OfferId of the product

selectPlanOnCashierPage
boolean
conditional

This parameter needs to be sent only in case of EMI Subvention through All-in-One SDK and JS checkout. Value should be "True" only.

subventionAmount
double
conditional

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

offerDetails
object
conditional

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

OfferDetail
+
AttributeDescription
offerId
string
mandatory

OfferId of the product

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

splitSettlementInfo
object
optional

Split payment details

SplitSettlementInfo
+
AttributeDescription
splitMethod
string
mandatory

Split method
Possible Values: AMOUNT, PERCENTAGE

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

goods
object
optional

Split merchant goods info list

shippingInfo
object
optional

Split merchant shipping info list

extendInfo
string
optional

This contains the Map which needs to be sent by merchant (ref1, ref2,...,ref12) and contains keys (ref1, ref2,...,ref12) and their corresponding value

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://<callback URL to be used by merchant>"},"head":{"signature":"{signature}"}}'  
copy icon