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
Head
Attribute | Description |
---|---|
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. |
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. |
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. | ||||||||||||||||||||||||||||||||||||||||||||||||
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 +
| |||||||||||||||||||||||||||||||||||||||||||||||||
userInfo object mandatory | User information contains user details like customer ID, email, phone number etc.
| ||||||||||||||||||||||||||||||||||||||||||||||||
UserInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||
PaymentMode +
| |||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||
PaymentMode +
| |||||||||||||||||||||||||||||||||||||||||||||||||
promoCode string optional | It is the code that has been applied during the transaction on the merchant website. | ||||||||||||||||||||||||||||||||||||||||||||||||
goods array of objects optional | This contain the goods info for an order | ||||||||||||||||||||||||||||||||||||||||||||||||
GoodsInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
shippingInfo object optional | This contain the shipping info for an order. | ||||||||||||||||||||||||||||||||||||||||||||||||
ShippingInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
extendInfo object optional | Merchant can pass any order specific information that is required to be passed here. | ||||||||||||||||||||||||||||||||||||||||||||||||
ExtendedInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
VanInfo object optional | Details of customer VAN. | ||||||||||||||||||||||||||||||||||||||||||||||||
VanInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
paymentOffersApplied string optional | In case of Offers based on Payment Instrument, inputs could be: paymentOffer parameter json string received in response of ApplyPromo API. 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. Example: { "promoCode":"TESTXXWALLET","applyAvailablePromo":"true","validatePromo":"false" } | ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedPaymentOffers +
| |||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedSubvention object optional | Object of Simplified subvention. | ||||||||||||||||||||||||||||||||||||||||||||||||
SimplifiedSubvention +
| |||||||||||||||||||||||||||||||||||||||||||||||||
emiSubventionToken string optional | Get emiSubventionToken from EMI Subvention - Validate API (Only for EMI - Subvention) | ||||||||||||||||||||||||||||||||||||||||||||||||
payableAmount object optional | Get finalTransactionAmount from EMI Subvention - Validate API and the currency type. (Only for EMI - Subvention) | ||||||||||||||||||||||||||||||||||||||||||||||||
Money +
| |||||||||||||||||||||||||||||||||||||||||||||||||
splitSettlementInfo object optional | Split payment details Note: Send only in case split settlement required | ||||||||||||||||||||||||||||||||||||||||||||||||
SplitSettlementInfo +
|
Response Attributes
Head
Attribute | Description |
---|---|
version string | Version of the API passed in the request. |
responseTimestamp string | EPOCH timestamp of the time at which response is being sent. |
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 +
| |||||||||||||||
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 |
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}"}}'