search

POSTPre-Auth API

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 are rejected by Paytm. It's alphanumeric and special character allowed are “@” “-” “_” “.”.

TXN_AMOUNT

mandatory

This is the PreAuth Amount that is to be charged

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.

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. It's 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 API call.
USER_WALLET_BALANCE This field contains user wallet balance after preauth txn.

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


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