Pre-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 if 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 when Preauth API is returning error code SR_1004, merchant needs to call Transaction Status API to know the exact status of order whether txn is success or failure

Request Attributes:

API Content format: JSON

NAMEDESCRIPTIONREQUIRED
MIDThis is the “Merchant Identifier” that is issued by Paytm to the Merchant. This is unique for each merchant that integrates with PaytmYes
ORDER_IDThe “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gatewayYes
TXN_AMOUNTThis is the PreAuth Amount that is to be chargedYes
TOKENThe token received from Paytm for that userYes
DURATIONHRSThis is duration for which merchant wants Paytm to block the amountNo
CHECKSUMChecksum generated by the merchant based on some logicYes

Response Attributes:

API Content format: JSON

NAMEDESCRIPTIONREQUIRED
ORDER_IDThe “Order ID” is the Merchant’s Transaction ID which should be unique for every transaction. Duplicate order id will be rejected by the Paytm gatewayYes
BLOCKEDAMOUNTThis is the amount that the Merchant raised a block request forYes
STATUSThe status of the Pre-auth request raised by the merchantYes
PREAUTH_IDThis is a unique ID generated by Paytm(acquirementId) against each Pre-auth RequestYes
STATUSCODEStatus code corresponding to status of txnYes
STATUSMESSAGEStatus message corresponding to status to txnYes
USER_WALLET_BALANCEThis field contains user wallet balance after preauth txnYes

Pre-Auth Status Codes and Messages


STATUS CODESTATUS MESSAGESTATUS
01Txn SuccessfulTXN_SUCCESS
100Paytm has classified this transaction as suspiciousTXN_FAILURE
118The transaction amount specified by the user exceeds the per transaction limit for this merchantTXN_FAILURE
130This user is blocked at Paytm endTXN_FAILURE
151Transaction with the same order Id already existsTXN_FAILURE
156Perday Txn amount is crossed for PaytmTXN_FAILURE
158PerMonth Txn amount is crossed for PaytmTXN_FAILURE
159Perday Txn count is crossed for PaytmTXN_FAILURE
161PerMonth Txn count is crossed for PaytmTXN_FAILURE
165User has crossed the monthly debit limit prescribed by RBITXN_FAILURE
227Transaction failedTXN_FAILURE
237Could not complete request. Please retry againTXN_FAILURE
240Invalid total amountTXN_FAILURE
238Invalid currency codeTXN_FAILURE
243Wallet not exist for the userTXN_FAILURE
267User does not existTXN_FAILURE
274User not verifiedTXN_FAILURE
327Channel is not associatedTXN_FAILURE
303Merchant Id can not be blankTXN_FAILURE
334Invalid Order IdTXN_FAILURE
343Invalid TokenTXN_FAILURE
344Invalid wallet typeTXN_FAILURE
345Request not uniqueTXN_FAILURE
350Duplicate order idTXN_FAILURE
357Invalid order IdTXN_FAILURE
403UNAUTHORIZED_ACCESSTXN_FAILURE
501System ErrorTXN_FAILURE
SR_1004Duplicate block request for Merchant Order IDTXN_FAILURE
GE_1007Invalid Transaction AmountTXN_FAILURE
WM_1006Your balance is insufficient for this request. Please add money in your wallet before proceedingTXN_FAILURE
RWL_2001You cannot do txns of amount greater than the allowed debit limit on your wallet.TXN_FAILURE
UDL_0015Daily limit for number of Payment to Merchant transactions will exceed. Please update limits and retryTXN_FAILURE
UDL_0014Daily limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retryTXN_FAILURE
UDL_0017Monthly limit for number of Payment to Merchant transactions will exceed. Please update limits and retryTXN_FAILURE
UDL_0016Monthly limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retryTXN_FAILURE
ATE_00042Balance Account not foundTXN_FAILURE
WM_1003Merchant does not existTXN_FAILURE
P2P_1000We could not get the requested details. Please try againTXN_FAILURE
RWL_0001You will exceed maximum number of allowed transactionsTXN_FAILURE
GE_1026We can not process your request. Please try laterTXN_FAILURE
GE_1041We could not get the requested details. Please try againTXN_FAILURE
GE_1035Merchant is in inactive stateTXN_FAILURE
VF_1009Could not pass velocity checkTXN_FAILURE
GE_1073PreAuth limit exceeded. You cannot block more amount for this userTXN_FAILURE

Pre-Auth Error Codes and Error Messages


ERROR CODEERROR MESSAGE
240Invalid total amount
305Merchant Id not registered
330Paytm checksum mismatch
332Order id can't be greater than 50 characters
501System Error
NO TOKENTOKEN IS REQUIRED
ORDER_ID NOT PRESENTORDER_ID IS REQUIRED
TXN_AMOUNT IS NOT PRESENTTXN_AMOUNT IS REQUIRED
VAER-CS103CHECKSUM IS REQUIRED
VAER-PF101VAL_PF_MID IS REQUIRED

Endpoints

Staging: https://securegw-stage.paytm.in/order/preAuth

Production: https://securegw.paytm.in/order/preAuth

Request CodeResponse JSON

curl -X POST 'https://securegw-stage.paytm.in/order/preAuth' --data-urlencode 
'JsonData={
    "MID":"xxxxxxxxxxxxxxxxxxxx",
    "ORDER_ID":"xxxxxxxxxxxxxxxxxxxxxxx",
    "TXN_AMOUNT":"1",
    "TOKEN":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "CHECKSUM":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'