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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

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

Attribute	Description
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

Attribute	Description
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 2, JS checkout and all-in-one SDK flows.

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

simplifiedPaymentOffers

Attribute

Description

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

cartDetails

object

conditional

SKU detail on which the Promo Code has to be applied.

Note: This is mandatory for SKU/Item based offer.

cartDetails

Attribute

Description

items

Array of Objects

mandatory

List of items

items

Attribute

Description

string

optional

Identified for every item generated by the merchant
Eg: “105”

amount

string

mandatory

Price of the product
Eg: "amount": “150”

productDetail

Object

mandatory

Information to identify the item

productDetail

Attribute	Description
id string mandatory	Product identifier configured in the bank offer Eg: "id": "123400232343411113e331" Note: This is the same value as passed in model attribute of simplifiedSubvention object in initiateTransaction API.
brandId string mandatory	Brand identifier configured in the bank offer Eg: "brandId": "1102" for Apple products Note: Currently only numeric values are supported
categoryIds Array of Strings mandatory	Category identified configured in the bank offer Eg: [ "521" ] for iPhones Note: Currently only numeric values are supported

simplifiedSubvention

object

optional

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

SimplifiedSubvention

Attribute

Description

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

Array of objects

conditional

Items for subvention (mandatory for product based subvention)

Item

Attribute

Description

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 e.g. LG, Sony etc. Should be send in the request if EMI plans are configured with brand attribute.

categoryList

Array of strings

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

offerDetails

object

mandatory

OfferId that is enabled on the product

OfferDetail

Attribute	Description
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

Attribute	Description
offerId string mandatory	OfferId of the product

emiSubventionToken

string

optional

Get emiSubventionToken from EMI Subvention - Validate API (Only for EMI - Subvention)
Example:a18fa0d896444b18a237d5XXXXdbc79e1576762049265

payableAmount

object

optional

Get finalTransactionAmount from EMI Subvention - Validate API/Apply Offer API and the currency type. (Only for EMI - Subvention)

Money

Attribute	Description
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

Attribute

Description

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

Attribute

Description

mid

string

mandatory

Child mid

amount

object

conditional

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

Amount

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

string

optional

Valid email of the user.

Example: vaibhav41094@gmail.com

extendInfo

string

optional

Extended info of goods.

extendInfo

Attribute	Description
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

Attribute

Description

promoDetails

object

conditional

Object to be passed for applying bank offer

promoDetails

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

resultInfo

object

This parameter gives the information about the result of the API response

ResultInfo

Attribute	Description
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

resultCode	resultStatus	resultMsg
0000	S	Success
0002	S	Success Idempotent
196	F	Payment 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.
1006	F	Your Session has expired
1007	F	Missing mandatory element
1008	F	Pipe character is not allowed
1011	F	Invalid Promo Param
1012	F	Promo amount cannot be more than transaction amount
2004	F	SSO Token is invalid
2005	F	Checksum provided is invalid
2007	F	Txn amount is invalid
2013	F	Mid in the query param doesn’t match with the Mid sent in the request
2014	F	OrderId in the query param doesn’t match with the OrderId sent in the request
2023	F	Repeat Request Inconsistent
00000900	U	System error

⇾

Staging

Production

https://securestage.paytmpayments.com/theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://securestage.paytmpayments.com/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}"}}'