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
Head
| Attribute | Description |
|---|---|
version string optional | Application version(provided by Paytm) |
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
| Attribute | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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. | ||||||||||||||||||
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). | ||||||||||||||||||
userInfo string mandatory | Details with respect to the user are shared in the object. | ||||||||||||||||||
userInfoPreAuth +
| |||||||||||||||||||
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
Head
| Attribute | Description |
|---|---|
responseTimestamp string | Timestamp at which response was sent |
version string | Application version(provided by paytm) |
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
| Attribute | Description |
|---|---|
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
| resultCode | resultStatus | resultMsg |
|---|---|---|
| 01 | TXN_SUCCESS | Txn Successful |
| 02 | PENDING | Txn Pending |
| 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 |
| 238 | TXN_FAILURE | Invalid currency code |
| 240 | TXN_FAILURE | Invalid total amount |
| 243 | TXN_FAILURE | Wallet not exist for the user |
| 267 | TXN_FAILURE | User does not exist |
| 274 | TXN_FAILURE | User not verified |
| 303 | TXN_FAILURE | Merchant Id can not be blank |
| 327 | TXN_FAILURE | Channel is not associated |
| 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 |
| GE_1041 | TXN_FAILURE | We could not get the requested details. Please try again |
| GE_1007 | TXN_FAILURE | Invalid Transaction Amount |
| GE_1026 | TXN_FAILURE | We can not process your request. Please try later |
| GE_1035 | TXN_FAILURE | Merchant is in inactive state |
| GE_1073 | TXN_FAILURE | PreAuth limit exceeded. You cannot block more amount for this user |
| VF_1009 | TXN_FAILURE | Could not pass velocity check |
| WM_1003 | TXN_FAILURE | Merchant does not exist |
| SR_1004 | TXN_FAILURE | Duplicate block request for Merchant Order ID |
| WM_1006 | TXN_FAILURE | Your balance is insufficient for this request. Please add money in your wallet before proceeding |
| P2P_1000 | TXN_FAILURE | We could not get the requested details. Please try again |
| UDL_0014 | TXN_FAILURE | Daily limit for total amount of Payment to Merchant transactions will exceed. Please update limits and retry |
| UDL_0015 | TXN_FAILURE | Daily 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 |
| UDL_0017 | TXN_FAILURE | Monthly limit for number of Payment to Merchant transactions will exceed. Please update limits and retry |
| RWL_0001 | TXN_FAILURE | You will exceed maximum number of allowed transactions |
| RWL_2001 | TXN_FAILURE | You cannot do txns of amount greater than the allowed debit limit on your wallet. |
| ATE_00042 | TXN_FAILURE | Balance 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 |
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"}}}'
