Data Loading...
PayTM_New_Web_Integration_Document-V3.2 Flipbook PDF
PayTM_New_Web_Integration_Document-V3.2
252 Views
111 Downloads
FLIP PDF 751.12KB
Paytm Payments Integration Document
One97 Communication Ltd. B -‐ 121, Sector 5, Noida – 201 301, India T. + 91 120 4770770
Email ID – [email protected] One97 Communication Ltd.
The information contained herein is confidential and proprietary to One97 Communication Ltd.. This document is issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify, reproduce or circulate part or whole of the information in this document without the written permission of One97 Communication Ltd.
Document Name: Paytm Payments Integration Manual
Document Version: V 3.2 Document Author: Operations Team Member Document Approver: Operations Manager
Revision History
S.No.
Date
Description
Version
Revised By
1
01/11/2012
Initial Version
1.0
Tarun Kumar
2
11/11/2012
Revised Version
2.0
Rajesh Arya
3
06/12/2012
Revised Version
2.1
Rajesh Arya
4
13/05/2013
Revised Version
2.2
Geetanshu Singla
5
01/10/2013
Revised Version
2.3
Nikhil Kumar
6
18/10/2013
Revised Version
2.4
Nikhil Kumar
7
26/02/2014
Revised Version
2.5
Nikhil Kumar
8
19/04/2014
Revised Version
2.6
Nikhil Kumar
9
04/06/2014
Revised Version
3.0
Nikhil Kumar
10
09/10/2014
Revised Version
3.1
Amit Kurseja
11
12/12/2014
Revised Version
3.2
Sukanth
Paytm Payments Integration Document
Page 2
Table of Contents Introduction ............................................................................................................................................................................. 3 Preliminary requirements for integration with Paytm ............................................................................................................. 4 How to raise a transaction request to Paytm's server? ........................................................................................................... 5 1.
Request parameters for Normal Transactions: ................................................................................................................ 5
2.
Request Parameters for Seamless Transaction ................................................................................................................ 9
3.
Request Parameters for Subscription Transaction ......................................................................................................... 12
4.
Request Parameters for Renewal Transaction ............................................................................................................... 17
Checksum Generation ............................................................................................................................................................ 21 Verifying Checksum in the Response ..................................................................................................................................... 21 PG URL’s ................................................................................................................................................................................... 5 How to read the response sent by Paytm? ............................................................................................................................ 21 Status Query API: ................................................................................................................................................................... 24 How to refund the transaction? ............................................................................................................................................. 26 Appendix A: Response Code List ............................................................................................................................................ 28
Introduction The Paytm payment gateway enables merchants to receive money from their customers by temporarily redirecting them to Paytm's web server.
The objective of this document is to explain the procedure for integration of Paytm payment platform with Paytm Payments Integration Document
Page 3
Merchant’s web application interface.
How does Paytm payment gateway works??
The Paytm payment gateway requires the merchant to modify their payment page to include Paytm as a payment option. Then, when the customer selects Paytm as a payment option, the merchant's web server actually POSTs an HTML form with the required fields as explained in the Request parameters table in the document. This sends a transaction request to Paytm's server.
The Paytm server then reads the submitted form and presents a payment page to the customer based on the payment mode received in the request parameter, wherein the customer fills the required payment (card) details. Then, the user might be redirected to bank's website for further authentication. Upon authentication, Paytm receives the response sent by the bank and POSTs it to the callback URL provided by the merchant. Merchant then reads the response parameters sent by Paytm and presents the transaction result to the customer on his own website.
Preliminary requirements for integration with Paytm
Following parameters are required for every merchant that wants to integrate with Paytm:
• Unique MID: Paytm generates a unique “MID” which is issued to the Merchant. This parameter is used to authorize the transaction request raised to Paytm's server. • Merchant Website’s Callback URL: Merchant n e e d s to provide P a y t m a public URL, where the
Paytm Payments Integration Document
Page 4
customer will be redirected after the completion of a transaction. The transaction details/status will also be sent by Paytm to this callback url. The callback url is a prerequisite for creating the Merchant ID.
How to raise a transaction request to Paytm's server? PG URL’s PG URL’s that merchant request should hit are given below. Dynamic Order_ID (explained in table below) needs to be be appended to each request as shown.
For production environment:
https://secure.paytm.in/oltp-‐web/processTransaction?orderid=
For staging environment:
https://pguat.paytm.com/oltp-‐web/processTransaction?orderid=
1. Request parameters for Normal Transactions: If REQUEST_TYPE=DEFAULT, then merchant needs to post below parameters. Mandatory Parameters S.No
Parameter Name
Description
Length
Alpha
50
1
REQUEST_TYPE
Type of transaction. Possible value : DEFAULT : For normal transaction flow
2
MID
This is the “Merchant Identifier” that is issued by Paytm to the Merchant. This is unique for each merchant that integrates with Paytm.
Alphanumeric
50
3
ORDER_ID
Alphanumeric
50
4
CUST_ID
The “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gateway. The “Customer ID” is the customer id e n t i f i e r . This c o u l d be a unique user Id that the M e r c h a n t h a s assigned to its customers. This parameter is required for correlating the user to a transaction. Multiple transactions can have the same Application User Name if the same customer is performing multiple transactions. The Application User Name is used by Paytm’s fraud prevention engine for detecting fraudulent transactions/users.
Alphanumeric
30
Paytm Payments Integration Document
Type
Page 5
Only alphanumeric characters are allowed. Special characters will be treated as errors.
5
TXN_AMOUNT
6
CHANNEL_ID
7
INDUSTRY_TYPE_ID
8
WEBSITE
9
CHECKSUMHASH
This is the “Transaction Amount” that is to be charged to the customer’s credit card /debit card /bank account / paytm Cash. Only numeric values are allowed. Please ensure that the amount is in the same currency as defined for the Merchant ID being used. Channel IDs need to pass in this parameter Exp: 1. WEB – for desktop websites 2. WAP – for mobile websites Industry type should pass here. This will be provided by paytm. Ex: “Recharge” WEBSITE Name should passed here .This will be provided by paytm.
Checksum calculated based on some logic. It is optional as per merchant’s configuration.
Amount
50
Alphanumeric
50
Alphanumeric
50
Alphanumeric
50
Alphanumeric
Optional Parameters
S.No 1
Parameter Name PAYMENT_MODE_ONLY
Description If Merchant wants to allow payment mode selection on his website.
Type Alphanumeric
Value: YES
2
AUTH_MODE
Possible values of this parameter:
Alphanumeric
3D – Credit/Debit card & Operator Billing payment mode USRPWD – for Net banking payment mode Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this Paytm Payments Integration Document
Page 6
feature as per merchant’s request.
3
PAYMENT_TYPE_ID
Possible values of this parameter: 1.
CC – for credit card payment mode
2.
DC – for debit card payment mode
3.
NB – for net banking payment mode
4.
Telco – for Operator Billing
5.
PPI – For Paytm Cash
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
4
CARD_TYPE
Possible values of this parameter: 1.
VISA
2.
MASTER
3.
AMEX
Alphanumeric
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
5
BANK_CODE
This parameter is mandatory to pass if customer is choosing Net banking option. Bank code’s list will be provided by Paytm upon request. Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
6
PROMO_CAMP_ID
This parameter is required to pass when merchant is Alphanumeric running any promotional campaign and it is configured at paytm payment gateway.
7
ORDER_DETAILS
Text which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
8
COMMENTS
Item counts which merchants wanted to displayed on
Alphanumeric
Paytm Payments Integration Document
Page 7
Paytm payment’s page.
9
DOB
Date of birth of customer
DATE
10
PAN_CARD
PAN number of customer
Alphanumeric
11
DL_NUMBER
Driving license number of customer
Alphanumeric
12
MSISDN
Mobile number of customer
13
EMAIL
Email ID of customer
14
VERIFIED_BY
Parameter will contain any one value mentioned below on which merchant has verified customer.
15
IS_USER_VERIFIED
1.
EMAIL
2.
MSISDN
YES – if merchant has verified customer on the field mentioned in “VERIFIED_BY” parameter.
Numeric
Alphanumeric Alphabets
Alphabets
NO – if merchant has not verified customer.
16
ADDRESS_1
Shipping Address 1
Alphanumeric
17
ADDRESS_2
Shipping Address 2
Alphanumeric
18
CITY
Shipping address’s city.
Alphanumeric
19
STATE
Shipping address’s state.
Alphanumeric
20
PINCODE
Shipping address’s pincode.
21
LOGIN_THEME
This parameter is used to display customized Paytm login page requested by merchant
22
Callback_URL
Merchant will get response on this URL if this parameter is sent in transaction request
23
THEME
Format: Theme|Subtheme
Paytm Payments Integration Document
Numeric
Alphanumeric
URL
Alphabets
Page 8
Default Value : merchant Theme used to display Paytm payment page. Subtheme is used to customize payment page as requested by merchant. 2.
Request Parameters for Seamless Transaction If merchant wants to put CC/DC details on his own website’s page, then he needs to post below parameters. Here REQUEST_TYPE = SEAMLESS
Mandatory Parameters
S.No
Parameter Name
Description
Length
Alpha
50
1
REQUEST_TYPE
Type of transaction. Possible value : SEAMLESS : For seamless transaction flow
2
MID
This is the “Merchant Identifier” that is issued by Paytm to the Merchant. This is unique for each merchant that integrates with Paytm.
Alphanumeric
50
3
ORDER_ID
Alphanumeric
50
4
CUST_ID
Alphanumeric
50
5
TXN_AMOUNT
Amount
50
6
CHANNEL_ID
The “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gateway. The “Customer ID” is the customer id e n t i f i e r . This c o u l d be a unique user Id that the M e r c h a n t h a s assigned to its customers. This parameter is required for correlating the user to a transaction. Multiple transactions can have the same Application User Name if the same customer is performing multiple transactions. The Application User Name is used by Paytm’s fraud prevention engine for detecting fraudulent transactions/users. Only alphanumeric characters are allowed. Special characters will be treated as errors. This is the “Transaction Amount” that is to be charged to the customer’s credit card /debit card /bank account / paytm Cash. Only numeric values are allowed. Please ensure that the amount is in the same currency as defined for the Merchant ID being used. Channel IDs need to pass in this parameter Exp: 1. WEB – for desktop websites 2. WAP – for mobile websites
Alphanumeric
50
Paytm Payments Integration Document
Type
Page 9
7
INDUSTRY_TYPE_ID
8
WEBSITE
9
PAYMENT_DETAILS
Industry type should pass here. This will be provided by paytm. Ex: “Recharge” WEBSITE Name should passed here .This will be provided by paytm.
Alphanumeric
50
Alphanumeric
50
This parameter has some specific encrypted format
Alphanumeric
100
Alphanumeric
50
Alphanumeric
50
Alphanumeric
Format is: cardNumber|cvvNUmber|expirydate expiryDate must be in format (MMYYYY) If MM is 7 then it must come like 07 Encrypt this with merchant key using utility EncryptionFactory.getEncryptionInstance(Encryp tConstants.ALGTHM_TYPE_AES).encrypt("cardNu mber|cvvNumber|expiryDate",“merchantKey”) it is present in same library as provided for creating CHECKSUMHASH. AUTH_MODE
10
Possible values of this parameter: 3D – Credit/Debit card payment mode
PAYMENT_TYPE_ID
11
CHECKSUMHASH
19
Possible values of this parameter: 1.
CC – for credit card payment mode
2.
DC – for debit card payment mode
Checksum calculated based on some logic. It is optional as per merchant’s configuration.
Optional Parameters
S.No
Parameter Name
Paytm Payments Integration Document
Description
Type
Page 10
1
CARD_TYPE
Possible values of this parameter: 1.
VISA
2.
MASTER
3.
AMEX
Alphanumeric
2
THEME
Purpose of this parameter is to apply themes on Paytm Payment page.
Alphanumeric
3
PROMO_CAMP_ID
This parameter is required to pass when merchant is running any promotional campaign and it is configured at paytm payment gateway.
Alphanumeric
4
ORDER_DETAILS
Text which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
5
COMMENTS
Item counts which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
6
DOB
Date of birth of customer
7
PAN_CARD
PAN number of customer
Alphanumeric
8
DL_NUMBER
Driving license number of customer
Alphanumeric
9
MSISDN
Mobile number of customer
10
EMAIL
Email ID of customer
11
VERIFIED_BY
Parameter will contain any one value mentioned below on which merchant has verified customer.
12
IS_USER_VERIFIED
1.
EMAIL
2.
MSISDN
YES – if merchant has verified customer on the field mentioned in “VERIFIED_BY” parameter.
Numeric
Alphanumeric Alphabets
Alphabets
NO – if merchant has not verified customer.
Paytm Payments Integration Document
Page 11
13
ADDRESS_1
Shipping Address 1
Alphanumeric
14
ADDRESS_2
Shipping Address 2
Alphanumeric
15
CITY
Shipping address’s city.
Alphanumeric
16
STATE
Shipping address’s state.
Alphanumeric
17
PINCODE
Shipping address’s pincode.
18
LOGIN_THEME
Numeric
Alphanumeric
3.
Request Parameters for Subscription Transaction If REQUEST_TYPE=SUBSCRIBE, then merchant needs to post below parameters.
Mandatory Parameters S.No Parameter Name
Decription
Length
Alpha
50
1
REQUEST_TYPE
Type of transaction. Possible value : SUBSCRIBE : For subscription transaction
2
MID
This is the “Merchant Identifier” that is issued by Paytm to the Merchant. This is unique for each merchant that integrates with Paytm.
Alphanumeric
50
3
ORDER_ID
The “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gateway.
Alphanumeric
50
4
CUST_ID
The “Customer ID” is the customer
Alphanumeric
Paytm Payments Integration Document
Type
50 Page 12
identifier. This could be a unique user Id that the Merchant has assigned to its customers. This parameter is required for correlating the user to a transaction. Multiple transactions can have the same Application User Name if the same customer is performing multiple transactions. The Application User Name is used by Paytm’s fraud prevention engine for detecting fraudulent transactions/users. 5
TXN_AMOUNT
This is the “Transaction Amount” that is to be charged to the customer’s credit/debit card. Only numeric values are allowed. Please ensure that the amount is in the same currency as defined for the Merchant ID being used.
Amount
50
6
CHANNEL_ID
Channel IDs need to pass in this parameter Exp: 1. WEB – for desktop websites 2. WAP – for mobile websites
Alphanumeric
50
7
INDUSTRY_TYPE_ID
Industry type should pass here. This will be provided by paytm. Ex: “Recharge”
Alphanumeric
50
8
WEBSITE
WEBSITE Name should passed here .This will be provided by paytm.
Alphanumeric
50
9
SUBS_SERVICE_ID
Subscription service identifier provided by the merchant
Alphanumeric
50
10
SUBS_AMOUNT_TYPE
Possible value : FIX/VARIABLE
Alpha
50
If possible value is VARIABLE then SUBS_MAX_AMOUNT parameter is
Paytm Payments Integration Document
Page 13
mandatory. 11
SUBS_FREQUENCY
Frequency value of a subscription
12
SUBS_FREQUENCY_UNIT
Possible values : DAY MONTH YEAR
NUMERIC
50
Alpha
50
Numeric
50
13
SUBS_ENABLE_RETRY
Flag specifying whether PG will retry a transaction in case of failure from Bank/Wallet due to some reason. Possible value : 0 or 1
14
SUBS_EXPIRY_DATE
Date when subscription will expire
Date in YYYY-‐ MM-‐DD format
50
Checksum calculated based on some logic. It is optional as per merchant’s configuration
Alphanumeric
15
CHECKSUMHASH
Optional Parameters
S.No
Parameter Name
Description
1
ORDER_DETAILS
Details of order. This will be displayed on payment page.
2
SUBS_MAX_AMOUNT
Maximum amount that can be deducted in a subscription request.
Type Text
Double
Mandatory: If SUBS_AMOUNT_TYPE=VARIABLE 3
SUBS_START_DATE
Next Subscription start date (in YYYY-‐MM-‐
Paytm Payments Integration Document
Date in YYYY-‐ Page 14
DD). Subscription cycle will be calculated based on this date and frequency
MM-‐DD format
Mandatory: If SUBS_GRACE_DAYS is sent in request. 4
SUBS_GRACE_DAYS
Number of days above cycle start date for which merchant can send request for renewal.
Integer
Mandatory: If SUBS_START_DATE is sent in request. THEME
Purpose of this parameter is to apply themes on Paytm Payment page.
Alphanumeric
6
PAYMENT_MODE_ONLY
If Merchant wants to allow payment mode selection on his website
Alphanumeric
7
AUTH_MODE
Possible values of this parameter:
Alphanumeric
5
3D – Credit/Debit card & Operator Billing payment mode USRPWD – for Net banking payment mode Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
8
PAYMENT_TYPE_ID
Possible values of this parameter:
Paytm Payments Integration Document
1.
CC – for credit card payment mode
2.
DC – for debit card payment mode
3.
NB – for net banking payment mode
4.
Telco – for Operator Billing
5.
PPI – For Paytm Cash
Alphanumeric
Page 15
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request. 9
CARD_TYPE
Possible values of this parameter: 4.
VISA
5.
MASTER
6.
AMEX
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
10
BANK_CODE
This parameter is mandatory to pass if customer is choosing Net banking option. Bank code’s list will be provided by Paytm.
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
11
PROMO_CAMP_ID
This parameter is required to pass when merchant is running any promotional campaign and it is configured at paytm payment gateway.
Alphanumeric
12
ORDER_DETAILS
Text which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
13
COMMENTS
Item counts which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
14
DOB
Date of birth of customer
DATE
15
PAN_CARD
PAN number of customer
Alphanumeric
Paytm Payments Integration Document
Page 16
16
DL_NUMBER
Driving license number of customer
17
MSISDN
Mobile number of customer
18
EMAIL
Email ID of customer
19
VERIFIED_BY
Parameter will contain any one value mentioned below on which merchant has verified customer.
20
IS_USER_VERIFIED
6.
EMAIL
7.
MSISDN
YES – if merchant has verified customer on the field mentioned in “VERIFIED_BY” parameter.
Alphanumeric Numeric
Alphanumeric Alphabets
Alphabets
NO – if merchant has not verified customer.
21
ADDRESS_1
Shipping Address 1
Alphanumeric
22
ADDRESS_2
Shipping Address 2
Alphanumeric
23
CITY
Shipping address’s city.
Alphanumeric
24
STATE
Shipping address’s state.
Alphanumeric
25
PINCODE
Shipping address’s pincode.
Numeric
4. Request Parameters for Renewal Transaction If REQUEST_TYPE= RENEW_SUBSCRIPTION, merchant need to POST only the following parameters in request
Mandatory Parameters Paytm Payments Integration Document
Page 17
S.No
Parameter Name
Description
Type
Length
1
REQUEST_TYPE
Type of transaction. Possible value : RENEW_SUBSCRIPTION: For subscription renewal
Alpha
50
2
MID
This is the “Merchant Identifier” that is issued by Paytm to the Merchant. This is unique for each merchant that integrates with Paytm.
Alphanumeric
50
3
ORDER_ID
The “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gateway.
Alphanumeric
50
4
SUBS_ID
Subscription Id given in response by PG to merchant in the first subscription request
Alphanumeric
50
5
TXN_AMOUNT
Subscription amount to be charged by customer
Amount
50
Alphanumeric
6
CHECKSUMHASH
Checksum calculated based on some logic. It is optional as per merchant’s configuration.
Optional Parameters
S.No
Parameter Name
Description
Type
1
PAYMENT_MODE_ONLY
If Merchant wants to allow payment mode selection on his website
Alphanumeric
2
AUTH_MODE
Possible values of this parameter:
Alphanumeric
3D – Credit/Debit card & Operator Billing payment mode USRPWD – for Net banking payment mode Paytm Payments Integration Document
Page 18
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
3
PAYMENT_TYPE_ID
Possible values of this parameter: 5.
CC – for credit card payment mode
6.
DC – for debit card payment mode
7.
NB – for net banking payment mode
8.
Telco – for Operator Billing
9.
PPI – For Paytm Cash
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
4
CARD_TYPE
Possible values of this parameter: 7.
VISA
8.
MASTER
9.
AMEX
Alphanumeric
Alphanumeric
Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
5
BANK_CODE
This parameter is mandatory to pass if customer is choosing Net banking option. Bank code’s list will be provided by Paytm. Mandatory: if merchant wanted to allow payment mode selection on his website. Paytm will enable this feature as per merchant’s request.
6
PROMO_CAMP_ID
This parameter is required to pass when merchant is running any promotional campaign and it is configured at paytm payment gateway.
Alphanumeric
7
ORDER_DETAILS
Text which merchants wanted to displayed on Paytm payment’s page.
Alphanumeric
Paytm Payments Integration Document
Page 19
8
COMMENTS
Item counts which merchants wanted to displayed on Paytm payment’s page.
9
DOB
Date of birth of customer
10
PAN_CARD
PAN number of customer
Alphanumeric
11
DL_NUMBER
Driving license number of customer
Alphanumeric
12
MSISDN
Mobile number of customer
13
EMAIL
Email ID of customer
14
VERIFIED_BY
Parameter will contain any one value mentioned below on which merchant has verified customer.
15
IS_USER_VERIFIED
3.
EMAIL
4.
MSISDN
YES – if merchant has verified customer on the field mentioned in “VERIFIED_BY” parameter.
Alphanumeric
Numeric
Alphanumeric Alphabets
Alphabets
NO – if merchant has not verified customer.
16
ADDRESS_1
Shipping Address 1
Alphanumeric
17
ADDRESS_2
Shipping Address 2
Alphanumeric
18
CITY
Shipping address’s city.
Alphanumeric
19
STATE
Shipping address’s state.
Alphanumeric
20
PINCODE
Shipping address’s pincode.
Numeric
•
Checksum must include all the parameters ( Mandatory/Optional) which will come in request i.e all the mandatory and optional parameters. So, merchant need to pass all the parameters to checksum utility method.
• •
All the mandatory parameters must come and must contain value. If Merchant wants to send any optional parameter in the request (Depending on requirement) then he needs to include it in CHECKSUMHASH as well.
Paytm Payments Integration Document
Page 20
•
Sometimes extra parameters come because of browser form submit or from framework then we will filter them out those parameters and will include only valid parameters in our CHECKSUMHASH.
•
If any optional parameter is empty then don’t include that parameter in your CHECKSUMHASH and even don’t send in request.
***Checksum is very important for security purpose. Merchant needs to create checksum by using the utility provided by Paytm. Checksum utility will be provided separately.
Checksum Generation According to technology used by merchant we provide checksum utility and user manual to use this utility.
Verifying Checksum in the Response Paytm sends the generated checksum in the response with parameter name CHECKSUMHASH. The code snippet for verifying checksum will be provided separately.
How to read the response sent by Paytm?
Response parameters sent by Paytm
S.no
Type
Mandatory
Unique subscription id generated by Paytm for identifying a subscription. Mandatory: If REQUEST_TYPE = SEAMLESS, SUBSCRIBE or RENEW_SUBSCRIPTION
Numeric
No
Alphanumeric
Yes
Numeric
Yes
Alphanumeric
Yes
Parameter
Description
1
SUBS_ID
2
MID
This is a unique merchant Id provided to merchant by Paytm at the time of merchant creation.
3
TXNID
This is a unique Paytm transaction Id that is issued by Paytm for each valid transaction request received from the merchant.
4
ORDERID
This is the a pplication transaction Id that was sent by merchant to Paytm at the time of transaction request.
Paytm Payments Integration Document
Page 21
Alphanumeric
Yes
The amount of the transaction.
Numeric
Yes
CURRENCY
Currency used for transaction. 1. INR 2. USD
Alphanumeric
Yes
8
STATUS
This contains the transaction status and has only two values: • TXN_SUCCESS • TXN_FAILURE
Alphanumeric
Yes
9
RESPCODE
This is a numeric transaction response code. “01” implies successful transaction. All other codes refer to a transaction failure with each code representing a different reason for failure. Refer to sheet mentioned in end of this document.
Alphanumeric
Yes
10
RESPMSG
This contains a short description of the transaction status. In case of a failed transaction the message will describe the potential reason for the failure.
Alphanumeric
Yes
11
TXNDATE
Date of transaction.
DateTime
Yes
12
GATEWAYNAME
The gateway used by Paytm (ICICI/CITI/WALLET etc).
Alphanumeric
Yes
13
BANKNAME
Bank name of the card issuing bank.
Alphanumeric
Yes
14
PAYMENTMODE
The payment mode used for transaction.
Alphanumeric
Yes
15
PROMO_CAMP_ID
This parameter will come in response only if merchant is running any promotional campaign and have passed the required parameters in transaction request. Promo should be configured at paytm payment gateway. Optional if merchant has not requested for any promo campaign.
Alphanumeric
No
16
PROMO_STATUS
This parameter will indicate whether Promo is successfully applied or failed. Below are values which may return in this parameter.
Alphanumeric
No
5
BANKTXNID
The transaction Id sent by the bank/wallet (NULL or empty string if the transaction doesn't reaches to the bank).
6
TXNAMOUNT
7
Paytm Payments Integration Document
Page 22
1. PROMO_SUCCESS 2. PROMO_FAILURE Optional if merchant has not requested for any promo campaign.
17
PROMO_RESPCODE
This is a numeric response code. “01” implies promo applied successfully. All other codes refer that promo has not been applied. Each code representing a different reason for failure. Refer to sheet mentioned in end of this document. Optional if merchant has not requested for any promo campaign.
Alphanumeric
No
18
CHECKSUMHASH
Checksum calculated based on some logic. It is optional as per merchant’s configuration.
Alphanumeric
Yes
***Once the response is received, the merchant must verify checksum using the utility provided by Paytm.
After successful integration, once the form is submitted, the customer will be redirected to the Paytm’s secure payment page if the payment mode is one of CC/DC/NB/Paytm Cash or any of the cash cards. On this page the customer will be required to choose the payment option. The screenshot of the Paytm payment page is shown below for reference.
When user clicks on proceed securely button, he may be redirected to bank's authentication page. Upon authentication bank sends the response to Paytm, which is then POSTed to Merchant's callback URL provided by the merchant.
Paytm Payments Integration Document
Page 23
Status Query API:
What is status query? Though Paytm uses SSL for transmission of data and checksum to ensure the integrity of the data being sent there are some un-‐avoidable circumstances under which the merchant may not receive the response. The scenarios are as follows – Consider that the payment details are submitted to some bank •
If bank server is down,
•
Customer’s browser will display error that bank’s URL is not reachable.
•
Paytm will not receive any response from bank.
•
Merchant will not receive any real-‐time parameters from Paytm.
•
If bank server sent a response and customer’s browser is closed for reasons whatsoever,
•
o
Paytm will not receive any response from bank.
o
Merchant will not receive any real-‐time parameters from Paytm.
If bank server sent a response and Paytm did not get any response from bank, o
Customer will not get any response from Paytm.
o
Merchant will not receive any real-‐time parameters from Paytm.
If bank server sent a response and Paytm posted response back to merchant but merchant did not receive any real-‐time parameters from Paytm for some reason. This clearly shows that in all circumstances, merchant will not receive any real-‐time parameters from Paytm. For some merchants, getting the status of each transaction in real-‐time is very critical as their next process cannot be initiated without knowing the fate of payment made by customer. Also there may be data transmission errors which lead to checksum mismatch at various points. To enable merchants to get or verify the transaction status, we are providing the transaction status tracking URL. •
It is basically a servlet which accepts merchant id (MID) and merchant’s order id (ORDERID) and retrieves the transaction status from the database. These parameters are to be posted through application over URLConnection using SSL. Status Query API for production environment: https://secure.paytm.in/oltp/HANDLER_INTERNAL/TXNSTATUS
Status Query API for staging environment: https://pguat.paytm.com/oltp/HANDLER_INTERNAL/TXNSTATUS
Paytm Payments Integration Document
Page 24
Request Parameters: (Should be passed as JSON string in “JsonData” parameter name)
S.no
Parameter Name
Description
Type
Length
Mandatory
Alphanumeric
Yes
50
Yes
1
MID
This is a unique merchant Id provided to merchant by Paytm at the time of merchant creation.
2
ORDERID
This is the a pplication transaction Id Alphanumeric that was sent by merchant to Paytm at the time of transaction request.
Response Parameters: (Response will come as JSON string) S.no
Parameter Name
Type
Mandatory
1
TXNID
This is a unique Paytm transaction Id that is issued by Paytm for each valid transaction request received from the merchant.
Numeric
Yes
2
BANKTXNID
The transaction Id sent by the bank (NULL or empty string if the transaction doesn't reaches to the bank).
Alphanumeric
Yes
3
ORDERID
This is the a pplication transaction Id that was sent by merchant to Paytm at the time of transaction request.
Alphanumeric
Yes
4
TXNAMOUNT
Amount of transaction.
Numeric
Yes
5
STATUS
This contains the transaction status and has only two values: • TXN_SUCCESS • TXN_FAILURE
Alphanumeric
Yes
6
TXNTYPE
Any one of below values: 1. SALE
Alphanumeric
Yes
7
GATEWAYNAME
The gateway used by Paytm (ICICI/CITI/WALLET etc).
Alphanumeric
Yes
8
RESPCODE
This is a numeric transaction response code. “01” implies successful transaction. All other codes refer to a transaction failure with each code representing a different reason for failure. Refer to sheet mentioned in end of this document.
Alphanumeric
Yes
Paytm Payments Integration Document
Description
Page 25
9
RESPMSG
10 BANKNAME
Alphanumeric This contains a short description of the transaction status. In case of a failed transaction the message will describe the potential reason for the failure. Bank name of the card issuing bank. Alphanumeric
Yes
Yes
11 MID
This is a unique merchant Id provided to merchant by Paytm at the time of merchant creation.
Alphanumeric
Yes
12 PAYMENTMODE
Mode of Payment. 1. CC 2. DC 3. NB 4. IMPS 5. PPI
Alphanumeric
Yes
13 REFUNDAMT
Total amount refunded till now if merchant has raised any requests.
Numeric
Yes
14 TXNDATE
Date of transaction.
DateTime
Yes
Response JSON String: {"TXNID":"62284943","BANKTXNID":"099172","ORDERID":"Test87984","TXNAMOUNT":"1","STATUS":"TXN_SUCCESS","TXNT YPE":"SALE","GATEWAYNAME":"CITI","RESPCODE":"01","RESPMSG":"Txn Successfull.","BANKNAME":"HDFC","MID":"xxxxx34213145601111","PAYMENTMODE":"CC","REFUNDAMT":"1","TXNDATE":" 2012-‐11-‐09 02:10:29.742447"}
How to refund the transaction? If the merchant, for any reason, wants to cancel or refund a success transaction, he can do so by simply sending a request to Paytm's server. Basic information needs to be sent across with the refund request. Following are the refund APIs and their request and response parameters. Refund API for production environment: https://secure.paytm.in/oltp/HANDLER_INTERNAL/REFUND
Refund API for staging environment: https://pguat.paytm.com/oltp/HANDLER_INTERNAL/REFUND
Request Parameters: (Should be passed as JSON string in “JsonData” parameter name)
S.no 1
Parameter Name MID
Description This is a unique merchant Id provided to merchant by Paytm at the time of merchant creation.
Paytm Payments Integration Document
Type
Mandatory
Alphanumeric
Yes
Page 26
2
TXNID
This is an unique Paytm transaction Id that is issued by Paytm for each valid transaction request received from the merchant.
3
ORDERID
This is the a pplication transaction Id that Alphanumeric was sent by merchant to Paytm at the time of transaction request.
4
REFUNDAMOUNT
Amount to be refunded.
Numeric
Yes
5 TXNTYPE
Any one of below values: 1. REFUND 2. CANCEL
Alphanumeric
Yes
6 COMMENTS
Any comments can be given here.
Alphanumeric
No
7 CHECKSUM
Checksum calculated based on some logic. It is optional as per merchant’s configuration.
Alphanumeric
Yes
Yes
Yes
Response Parameters: (Response will come as JSON string) S.no
Parameter Name
Description
1 MID
This is a unique merchant Id provided to merchant by Paytm at the time of merchant creation.
2 TXNID
This is a unique Paytm transaction Id that is issued by Paytm for each valid transaction request received from the merchant. This is the a pplication transaction Id that was sent by merchant to Paytm at the time of transaction request.
3 ORDERID
Type
Mandatory
Alphanumeric
Yes
Numeric
Yes
Alphanumeric
Yes
4 TXNAMOUNT
Amount of transaction.
Numeric
Yes
5 REFUNDAMOUNT
Amount to be refunded.
Numeric
Yes
6 TXNDATE
Date of transaction.
DateTime
Yes
7 RESPCODE
This is a numeric transaction response code. “01” implies successful transaction. All other codes refer to a transaction failure with each code representing a different reason for failure. Refer to sheet mentioned in end of this document.
Alphanumeric
Yes
Paytm Payments Integration Document
Numeric
Page 27
8 RESPMSG
9 STATUS
This contains a short description of the transaction status. In case of a failed transaction the message will describe the potential reason for the failure. This contains the transaction status and has only two values: • TXN_SUCCESS • TXN_FAILURE
Alphanumeric
Yes
Alphanumeric
Yes
Response JSON String: {"MID":"xxxxg3421314561111","ORDERID":"Test87984","TXNID":"62284943","TXNAMOUNT":"1","REFUNDAMOUNT": "1","TXNDATE":"2012-‐11-‐09 02:10:29.742447","RESPCODE":"330","RESPMSG":"Paytm checksum mismatch.","STATUS":"TXN_FAILURE"
Appendix A: Response Code List
01 03 04 05 06 08 09 10 100
Txn Successfull. NO_RESP_TIMEOUT Fail Closed Open Pending Failure to success after status query with bank. OTP sent to your registered phone. Refund Successfull. Paytm has classified the transaction as suspicious
101
The maximum limit on the number of users allowed to use this card as been reached. Please use another card for your transaction.
102
The user attempted the transaction with more cards than specified limit in the last 1 year. The transaction has been classified as suspicious and is blocked.
103
The user has made 3 unsuccessful attempts with the same card. The transaction has been classified as suspicious and the card has been blocked.
105 106 107 108 109 120
The user has made 3 unsuccessful attempts. The transaction has been classified as suspicious and user has been blocked. Max Txn amount is crossed for Cust Id Perday Txn amount is crossed for Cust Id PerWeek Txn amount is crossed for Cust Id PerMonth Txn amount is crossed for Cust Id Perday Txn count is crossed for Cust Id
Paytm Payments Integration Document
Page 28
121 122 110 111 112 113 114 115 116
PerWeek Txn count is crossed for Cust Id PerMonth Txn count is crossed for Cust Id Max Txn amount is crossed on Customer Card Number Perday Txn amount is crossed on Customer Card Number PerWeek Txn amount is crossed on Customer Card Number PerMonth Txn amount is crossed on Customer Card Number Perday Txn count is crossed on Customer Card Number PerWeek Txn count is crossed on Customer Card Number PerMonth Txn count is crossed on Customer Card Number
117
The user has breached the limit of maximum number of different cards allowed. The transaction can be completed with a previously used card.
118 119 123 124 125 126 127 128 129 130 131 132 133 134 140 141 150 151 152
The transaction amount specified by the user exceeds the per transaction limit for this merchant. Perday Txn amount is crossed Max Txn amount is crossed for NetBanking Transactions PerDay Txn amount is crossed for NetBanking Transactions PerWeek Txn amount is crossed for NetBanking Transactions PerMonth Txn amount is crossed for NetBanking Transactions Perday Txn count is crossed for NetBanking Transactions PerWeek Txn count is crossed for NetBanking Transactions PerMonth Txn count is crossed for NetBanking Transactions USER is blocked at Paytm end. Credit Card is blocked at Paytm end. IP Address is blocked at Paytm end. Mobile No. is blocked at Paytm end. Subscriber is blocked with the given DL Number,PAN Card,Email Id and MSISDN Invalid Input Parameter from Merchant Cancel Request by Customer Duplicate Transaction as similar transaction was seen in 30 sec Transaction with the same order Id already exists Merchant is not associated with channel
153
Channel is not configured with the Payment Mode,Auth Mode and Communication Mode.
155
Per Txn amount is crossed for wallet
156
Perday Txn amount is crossed for wallet
157
PerWeek Txn amount is crossed for wallet
158
PerMonth Txn amount is crossed for wallet
159
Perday Txn count is crossed for wallet
160
PerWeek Txn count is crossed for wallet
161
PerMonth Txn count is crossed for wallet
Paytm Payments Integration Document
Page 29
162
Maximum wrong attempts limit allowed crossed for wallet
163
Could not pass velocity check for wallet
164 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
Wallet through put limit failure.
223 224 225 226 227 228 229 230 231 232 233 234 235 236
A duplicate transaction was being attempted at the bank. Transaction has been declined. We are experiencing delays from the Bank. Timeout from bank some error at response parsing Txn Failed Acquirer bank has been unable to authorize the transaction. 3D Secure Verification failed 3D Secure Verification successful Only Indian AMEX cards are allowed Invalid account details.
OTP request failed. Bank has blocked the card used to transact. User does not have enough credit limit. Bank has declined the transaction. Card details entered by the user is/are invalid. Bank has declined the credit card used to transact. Transaction has been declined by the bank. A duplicate transaction was being attempted at the bank. Card details entered by the user is/are invalid. Transaction has been declined by the acquirer bank. Card details entered by the user is/are invalid. Lost Card received. Failure received from bank. Transaction is on hold by bank. Please check the status after some time. Encryption error at bank Suitable acquirer not found. Failure received from bank. Failure received from Bank gateway. Gateway error. OTP Validated User has entered an invalid OTP (One Time Password) Bank communication error. Checksum generated by Paytm Payment Gateway does not match checksum expected by Bank. Transaction amount return by the gateway does not match with Paytm transaction amount.
Authorization Failed. Invalid Username/Password. Insufficent balance. Wallet does not exist.
Paytm Payments Integration Document
Page 30
237 238 239 240 241 242 243 244 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
Could not complete request. Please retry again. Invalid currency code. Merchant does not exist. Invalid total amount. First Txn Failed Child Txn auto refunded. Wallet Not Created. Wallet Not Activated.
Invalid Json Request. Invalid Request type. Merchant Id can not be blank. App IP is blank. Merchant Id not registerd. Merchant Id expired. Security key expired. Invalid amount Invalid order id Invalid currency Invalid device id Invalid card number Invalid stored card id Invalid month Invalid year Invalid CVV Invalid payment mode Invalid customer id Invalid industry type Invalid card store flag Invalid card delete flag Card details not found User is blocked Duplicate customer id Duplicate order id Merchant is not associated Channel is not associated Invalid PaytmId Invalid OTP Paytm checksum mismatch. Record not found. Order id can't be greater than 50 characters.
Paytm Payments Integration Document
Page 31
333 334 335 336 400 401 402 501 502 503 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 699 700 701 810
Customer id can't be greater than 50 characters. Invalid Order Id. Invalid merchant Id. Invalid transaction type. Transaction status not confirmed yet. Invalid transaction. Abandoned Transaction. System Error. Json Encoding error. Fee not configured for this card category type. Invalid refund request. Refund request was raised for this transaction. But it is pending state. Bank has declined refund request. Refund/Cancel for the same transaction has already been initiated for the day. We are experiencing delays from the Bank. Refund initiated for a transaction, which is not settled. Checksum generated by Paytm Payment Gateway does not match checksum expected by Bank. Refund can not be initiated for a cancelled transaction. Paytm Payment Gateway has provided a wrong Auth number for the refund request. Refund initiated for a rejected transaction. Transaction fully refunded already Refund request is in process. This is a valid authorized transaction, but could not be cancelled due to operational reasons. Auto refund request is in process. Refund request is in process. CLW Refund to Wallet request failed. CLW Returns error response Refund request is already in process for the same id. Wallet of user not created. Wallet Refund Failed. It will be retried for next 48 hr. Auto Refund Failed. It will be retried for next 48 hr. Invalid ref id. Incomplete transaction
Paytm Payments Integration Document
Page 32
Paytm Payments Integration Document
Page 33