search

POSTPre-Auth API v1

Use Case

Flow ensures a fixed amount being Pre Auth'ed or blocked from user's wallet, rendered unusable on other merchants till a capture/release or timeout.

  • In case PAYTM returns insufficient balance in preauth response (status code WM_1006) then merchant needs to retry the preauth with new order id.preauth id of pre-auth API can be of upto 64 digits.
  • In case Preauth API is returning error code SR_1004, then the merchant needs to call Transaction Status API to know the exact status of order whether txn is success or failure.

Request Attributes

API Content Type: JSON

ATTRIBUTE DESCRIPTION

MID

string(20)
mandatory

This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different on staging and production environment. Your staging MID is available here & production MID will be available once your activation is complete.

ORDER_ID

string(50)
mandatory

Unique reference ID for an Order request which is generated by merchant and sent in the transaction request payload. Duplicate order request is rejected by Paytm. It's alphanumeric and special character allowed are “@” “-” “_” “.”.

TXN_AMOUNT

mandatory

This is the PreAuth Amount that is to be charged.
PAYMODE
optional
This is the paymode provided by merchant. Its value can be BALANCE, PAYTM_DIGITAL_CREDIT, UPI, or null.

TOKEN

mandatory

This is a unique token linked with user's Paytm wallet and is provided in the response while linking user's Paytm Wallet.

DURATIONHRS

optional

This is the duration for which merchant wants Paytm to block the amount.

CHECKSUM

string(108)
mandatory

Signature encryption for validation. It's value to be sent should be the checksum string created by using Paytm checksum library.
Note: Create the signature using all the request parameters.
TXNTOKEN_REQUIRED
optional
Flag to determine if txntoken needs to be sent in response. Payments for these preauth will be done using theia and should be true in case of UPI.
WEBSITE_NAME
optional

Only required, if paymode in the request is UPI(Multi-step flow).

If paymode is null and agreement flow merchant is false then check if its UPI paymode enabled on that case this field required(Multi-step flow).

MERCHANT_USER_DETAILS
Merchant User Details

optional

Required, only in case of Multi-step Flow. 

CALLBACK_URL

optional

This is an optional field which can be present in Multi-step Flow.

Merchant User Details

 
ATTRIBUTE DESCRIPTION

USERID

mandatory

User ID of the merchant

MOBILE

optional

Mobile number of the merchant

EMAIL

optional

Email ID of the merchant

FIRSTNAME

optional

First name of the merchant

LASTNAME

optional

Last name of the merchant

ADDRESS

optional

Address of the merchant

PINCODE

optional

Pincode associated with merchant's address

DISPLAYNAME

optional

Display name of the merchant

Response Attributes

API Content Type: JSON

ATTRIBUTE DESCRIPTION

ORDER_ID

string(50)

Unique reference ID for an Order request which is generated by merchant and sent in the transaction request payload. Duplicate order request are rejected by Paytm. It's alphanumeric and special character allowed are “@” “-” “_” “.”.
BLOCKEDAMOUNT This is the amount that a merchant raised a block request for.
PREAUTH_ID This is a unique ID generated by Paytm(acquirementId) against each Pre-auth Request.

STATUSCODE

string

This is corresponding to a particular message and is returned to the merchant. Its maximum length is 64. The different result codes corresponding to this API are mentioned below.

STATUSMESSAGE

string(30)

This parameter is the result message which contains information about the result.

STATUS

string(20)

This parameter indicates the status of the API call.

USER_WALLET_BALANCE

optional

This field contains user wallet balance after preauth txn.

TXN_TOKEN

optional

Only present in case of multi-step flow.

 

Response Codes & Messages

STATUSCODESTATUSMESSAGE
01 TXN_SUCCESS Txn Successful
100 TXN_FAILURE Paytm has classified this transaction as suspicious
118 TXN_FAILURE The transaction amount specified by the user exceeds the per transaction limit for this merchant
130 TXN_FAILURE This user is blocked at Paytm end
151 TXN_FAILURE Transaction with the same order Id already exists
156 TXN_FAILURE Perday Txn amount is crossed for Paytm
158 TXN_FAILURE PerMonth Txn amount is crossed for Paytm
159 TXN_FAILURE Perday Txn count is crossed for Paytm
161 TXN_FAILURE PerMonth Txn count is crossed for Paytm
165 TXN_FAILURE User has crossed the monthly debit limit prescribed by RBI
227 TXN_FAILURE Transaction failed
237 TXN_FAILURE Could not complete request. Please retry again
240 TXN_FAILURE Invalid total amount
238 TXN_FAILURE Invalid currency code
243 TXN_FAILURE Wallet not exist for the user
267 TXN_FAILURE User does not exist
274 TXN_FAILURE User not verified
327 TXN_FAILURE Channel is not associated
303 TXN_FAILURE Merchant Id can not be blank
334 TXN_FAILURE Invalid Order Id
343 TXN_FAILURE Invalid Token
344 TXN_FAILURE Invalid wallet type
345 TXN_FAILURE Request not unique
350 TXN_FAILURE Duplicate order id
357 TXN_FAILURE Invalid order Id
403 TXN_FAILURE UNAUTHORIZED_ACCESS
501 TXN_FAILURE System Error
SR_1004 TXN_FAILURE Duplicate block request for Merchant Order ID
GE_1007 TXN_FAILURE Invalid Transaction Amount
WM_1006 TXN_FAILURE Your balance is insufficient for this request. Please add money in your wallet before proceeding
RWL_2001 TXN_FAILUREYou cannot do txns of amount greater than the allowed debit limit on your wallet.
UDL_0015 TXN_FAILUREDaily limit for number of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0014 TXN_FAILUREDaily limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0017 TXN_FAILUREMonthly limit for number of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0016 TXN_FAILUREMonthly limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry
ATE_00042 TXN_FAILUREBalance Account not found
WM_1003 TXN_FAILUREMerchant does not exist
P2P_1000 TXN_FAILUREWe could not get the requested details. Please try again
RWL_0001 TXN_FAILUREYou will exceed maximum number of allowed transactions
GE_1026 TXN_FAILURE We can not process your request. Please try later
GE_1041 TXN_FAILURE We could not get the requested details. Please try again
GE_1035 TXN_FAILURE Merchant is in inactive state
VF_1009 TXN_FAILURE Could not pass velocity check
GE_1073 TXN_FAILURE PreAuth limit exceeded. You cannot block more amount for this user
02 PENDING Txn Pending


Pre-Auth Error Codes and Error Messages


ErrorCode ErrorMessage  
240 Invalid total amount  
305 Merchant Id not registered  
330 Paytm checksum mismatch  
332 Order id can't be greater than 50 characters  
501 System Error  
NO TOKEN TOKEN IS REQUIRED  
ORDER_ID NOT PRESENT ORDER_ID IS REQUIRED  
TXN_AMOUNT IS NOT PRESENT TXN_AMOUNT IS REQUIRED  
VAER-CS103 CHECKSUM IS REQUIRED  
VAER-PF101 VAL_PF_MID IS REQUIRED
WEBSITE_NAME IS NOT PRESENT Website Name is required for a transaction
MERCHANT_USER_DETAILS IS NOT PRESENT Payment failed as USERID inside MERCHANT_USER_DETAILS is missing
⇾
Staging
Production
https://securegw-stage.paytm.in/order/preAuthcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/order/preAuth' \
--header 'Content-Type: application/json' \
--data '{"MID":"{mid}","ORDER_ID":"ORDERID_98765","TXN_AMOUNT":"1.00","TOKEN":"eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..xxxxxxxxxxx.9iHTtWbCZ0I6qbn2sUnyz5siw1fqbmtEnFMFE7nSIX-yrwCkiGfAC6QmPr9q-tw8LMPOh5-3UXRbpeVZEupQd3wNyaArWybRX2HAxJDRD8mxJ_wxzJM6GZ1ov4O3EIsx2Y_Zr0aHCd3VbnTjRUnlVdxXJPFG8QZs0b_2TVdoAX3_QjZS8_dwcmIWoH8ebDzOIs7MJacETfMtyFGAo8Xc0LjznToUWvTsTbIXQoF1yB0.1fZFAYJVsY61BTv2htLcXQ8800","CHECKSUM":"{checksum}"}'      
        
copy icon