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) |
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) |
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) |
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 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 |
|
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
| STATUSCODE | STATUS | MESSAGE |
|---|---|---|
| 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_FAILURE | You cannot do txns of amount greater than the allowed debit limit on your wallet. |
| UDL_0015 | TXN_FAILURE | Daily limit for number of Payment to Merchant transactions will exceed. Please update limits and retry |
| UDL_0014 | TXN_FAILURE | Daily limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry |
| UDL_0017 | TXN_FAILURE | Monthly limit for number of Payment to Merchant transactions will exceed. Please update limits and retry |
| UDL_0016 | TXN_FAILURE | Monthly limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry |
| ATE_00042 | TXN_FAILURE | Balance Account not found |
| WM_1003 | TXN_FAILURE | Merchant does not exist |
| P2P_1000 | TXN_FAILURE | We could not get the requested details. Please try again |
| RWL_0001 | TXN_FAILURE | You 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/preAuth
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}"}'
