search

POSTPre-Auth API

Use Case

Flow ensures a fixed amount being Pre Auth'ed or blocked from the user's account, 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. Pre-auth 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

Content Type : JSON

Head

AttributeDescription
version
string
optional

Application version(provided by Paytm)
Example : 1.0.0

channelId
string
optional

The parameter value identifies the Channel for which API call is initiated.

Example: APP, WEB, WAP, SYSTEM

requestTimestamp
string
optional

Unix Timestamp of request

clientId
string
mandatory

Paytm uses the merchant key on the basis of clientId parameter value. It is required only if the merchant has more than one key.

signature
string
mandatory

Checksum string created by using paytm checksum logic/library

Body

AttributeDescription
mid
string
mandatory

This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different in staging and production environment.

orderId
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 characters allowed are “@” “-” “_” “.”.

txnAmount
string
mandatory

This is the PreAuth Amount that is to be charged.
Example : 835.00

paymentMode
string
optional

This is the paymode provided by the merchant. Its value can be BALANCE, PAYTM_DIGITAL_CREDIT, UPI, CREDIT_CARD, DEBIT_CARD or null.

paytmSsoToken
string
optional

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

This field only required if  PAYMODE is BALANCE or PAYTM_DIGITAL_CREDIT

preAuthBlockSeconds
string
optional

The max period (in seconds) for which the merchant wants to block the amount in the customer's account.

Example : 12321

websiteName
string
optional

Only required if paymode in request  is UPI or Credit/Debit card (Multi step Flow).
If paymode is null and agreement flow merchant is false then check if its UPI or Credit/Debit card paymode enabled in that case this field is required(Multi step Flow).

userInfo
string
mandatory

Details with respect to the user are shared in the object.

userInfoPreAuth
+
AttributeDescription
custId
string
mandatory

This parameter is the unique reference ID for every customer and is generated by the merchant. The allowed special characters for this parameter are @, ! ,_ ,$, .

mobile
string
optional

Mobile number of the merchant

email
string
optional

Email ID of the merchant

firstName
string
optional

First name of the merchant

lastName
string
optional

Last name of the merchant

address
string
optional

Address of the merchant

pincode
string
optional

Pincode associated with merchant's address

displayName
string
optional

Display name of the merchant

callbackUrl
string
optional

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

cardPreAuthType
string
optional

The type of Pre-Auth flow - Standard/Delayed that is to be used for the pr-auth transaction

Example : STANDARD_AUTH, DELAYED_AUTH

 

STANDARD_AUTH : This pre-auth flow involves blocking of amount in the customer’s account to be captured/released at a later stage.

DELAYED_AUTH : This flow involves no blocking of amount but only the authorization for this transaction is done at a later stage.

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string

Timestamp at which response was sent

version
string

Application version(provided by paytm)
Example : 1.0.0

clientId
string

Paytm uses the merchant key on the basis of clientId parameter value. It is required only if the merchant has more than one key.

signature
string

Checksum string created by using paytm checksum logic/library

Body

AttributeDescription
orderId
string

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

blockedAmount
string

This is the amount that a merchant raised a block request for. This will be provided only when paymentMode = BALANCE, PAYTM_DIGITAL_CREDIT

preAuthId
string

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

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

status
string

This parameter indicates the status of the API call.Pending in case of Multi step Flow.

txnToken
string

Only present in case of multi-step flow.

Response Codes & Messages

resultCoderesultStatusresultMsg
01TXN_SUCCESSTxn Successful
02PENDINGTxn Pending
100TXN_FAILUREPaytm has classified this transaction as suspicious
118TXN_FAILUREThe transaction amount specified by the user exceeds the per transaction limit for this merchant
130TXN_FAILUREThis user is blocked at Paytm end
151TXN_FAILURETransaction with the same order Id already exists
156TXN_FAILUREPerday Txn amount is crossed for Paytm
158TXN_FAILUREPerMonth Txn amount is crossed for Paytm
159TXN_FAILUREPerday Txn count is crossed for Paytm
161TXN_FAILUREPerMonth Txn count is crossed for Paytm
165TXN_FAILUREUser has crossed the monthly debit limit prescribed by RBI
227TXN_FAILURETransaction failed
237TXN_FAILURECould not complete request. Please retry again
238TXN_FAILUREInvalid currency code
240TXN_FAILUREInvalid total amount
243TXN_FAILUREWallet not exist for the user
267TXN_FAILUREUser does not exist
274TXN_FAILUREUser not verified
303TXN_FAILUREMerchant Id can not be blank
327TXN_FAILUREChannel is not associated
334TXN_FAILUREInvalid Order Id
343TXN_FAILUREInvalid Token
344TXN_FAILUREInvalid wallet type
345TXN_FAILURERequest not unique
350TXN_FAILUREDuplicate order id
357TXN_FAILUREInvalid order Id
403TXN_FAILUREUNAUTHORIZED_ACCESS
501TXN_FAILURESystem Error
GE_1041TXN_FAILUREWe could not get the requested details. Please try again
GE_1007TXN_FAILUREInvalid Transaction Amount
GE_1026TXN_FAILUREWe can not process your request. Please try later
GE_1035TXN_FAILUREMerchant is in inactive state
GE_1073TXN_FAILUREPreAuth limit exceeded. You cannot block more amount for this user
VF_1009TXN_FAILURECould not pass velocity check
WM_1003TXN_FAILUREMerchant does not exist
SR_1004TXN_FAILUREDuplicate block request for Merchant Order ID
WM_1006TXN_FAILUREYour balance is insufficient for this request. Please add money in your wallet before proceeding
P2P_1000TXN_FAILUREWe could not get the requested details. Please try again
UDL_0014TXN_FAILUREDaily limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0015TXN_FAILUREDaily limit for number of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0016TXN_FAILUREMonthly limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry
UDL_0017TXN_FAILUREMonthly limit for number of Payment to Merchant transactions will exceed. Please update limits and retry
RWL_0001TXN_FAILUREYou will exceed maximum number of allowed transactions
RWL_2001TXN_FAILUREYou cannot do txns of amount greater than the allowed debit limit on your wallet.
ATE_00042TXN_FAILUREBalance Account not found


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  
703 Card Pre-Auth Type is Invalid  
704 Duration hours exceed the allowed value  
801 paytmSsoToken IS REQUIRED  
802 orderId is required  
803 txnAmountIS REQUIRED  
804 signature is required  
805 websiteName is required for a transaction  
806 Payment failed as custId inside userInfo is missing  
⇾
Staging
Production
https://securegw-stage.paytm.in/order/v2/preAuthcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/order/v2/preAuth' \
--header 'Content-Type: application/json' \
--data '{"head":{"requestTimestamp": "1539601338741","clientId": "C11","version": "v2","channelId": "WEB","signature": "KVQ5YrYS/pcQtZ0gghKLWc="},"body":{"preAuthBlockSeconds":"70","mid":"{mid}","ORDER_ID":"ORDERID_98765","txnAmount":"1.00","websiteName":"RETAIL","paymentMode":"DEBIT_CARD","carPreAuthType":"DELAYED_AUTH","userInfo":{"custId":"12"}}}'      
        
copy icon