POSTValidation Services- Sync API

Use Case

Note: As of now Payouts through Bank transfer/UPI paymodes are not available.

This API is used to validate user wallet details in sync manner.

HTTP Headers

ATTRIBUTE	DESCRIPTION
x-mid string(50) mandatory	Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.
x-checksum string(108) mandatory	Signature encryption for validation. It's value to be sent should be the checksum string created by using the Paytm checksum library. Note: Create the signature using all the request parameters.

ATTRIBUTE

DESCRIPTION

x-mid

string(50)
mandatory

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.

x-checksum

string(108)
mandatory

Signature encryption for validation. It's value to be sent should be the checksum string created by using the Paytm checksum library.
Note: Create the signature using all the request parameters.

Request Attributes

API Content Type: JSON

ATTRIBUTE	DESCRIPTION
orderId string mandatory	It should be alphanumeric, orderId is merchant’s unique reference ID for a validate beneficiary account transaction passed in the request. This is Order ID for which the account validation order status needs to be fetched. Length should be 50 characters or less.
subwalletGuid string mandatory	Merchants sub wallet guid
beneficiaryPhoneNo string optional	Phone number of beneficiary
callbackUrl string(255) optional	Paytm sends the response of transaction on the URL which comes in the callbackUrl parameter.
custParam1 string optional	Value of custParam1 on basis of which we will check for the velocity limit. It is an optional field, if not present in input we will not apply velocity limit configured on custParam1 or any of its combination.
custParam2 string optional	Value of custParam2 on basis of which we will check for the velocity limit configured on custParam2 or any of its combinations.
skipVelocityRules boolean optional	Boolean value to disable velocity check. If true we will not apply the velocity counter.
skipCache boolean optional	Boolean value to skip the cache logic for penny drop
limitCheckAmount string optional	Merchant can send this amount to check the limit of the amount that can be transferred to the beneficiary's wallet.
nameValidationRequired boolean optional	Key true, if merchant want to validate their name validate(only applicable for wallet validation)
beneficiaryName string optional	Beneficiary name for wallet validation if "nameValidationRequired" is true

Response Attributes

API Content Type: JSON

ATTRIBUTE	DESCRIPTION
statusCode string	Failure reason code where status is FAILURE. A detailed list of statusCode is mentioned at the bottom of this page.
status string	This attribute should be used to fetch the final status of the order. It can be FAILURE, PENDING, ACCEPTED, and SUCCESS.
statusMessage string	Description of each statusCode.
mid string	This is a unique identifier provided to every merchant by Paytm
orderId string	It should be alphanumeric, orderId is the merchant’s unique reference ID for a validate beneficiary account transaction passed in the request. This is the Order ID for which the account validation order status needs to be fetched. Length should be 50 characters or less.
paytmOrderId string	Unique orderId generated by Paytm for each transaction
amount string	Transferred amount to the beneficiary
commissionAmount string	Commission charged on this transaction
tax string	Tax deducted on this transaction
rrn string	Unique identification number provided by the bank for bank transactions
beneficiaryName string	Name of beneficiary
isFoodWalletAvailable boolean	This key only enable for those merchants who have "ROLE_WALLETVALIDATION_KYCDETAILS" this permission
isWalletExists boolean	Wallet exists or not for corresponding beneficiaryPhoneNo
isNameMatched boolean	If merchant validates the "benificiaryName" with "nameValidationRequired" true then this key will come.
isLimitBreached boolean	Wallet transfer limit whether it's valid for transfer or not
isNameValidated boolean	Whether the merchant is validating beneficiary name or not

Response Codes & Messages

resultCode	resultStatus	resultMsg
DE_001	SUCCESS	Successful disbursal to Bank Account is done.

DE_002	ACCEPTED	Request accepted
DE_010	FAILURE	param is mandatory and it's can't be null or blank
DE_011	FAILURE	param doesn't contain a valid value
DE_012	FAILURE	Amount must be a positive number with maximal 2 decimal places
DE_013	FAILURE	param doesn't contain valid length, It should be <length> or less
DE_015	FAILURE	Purpose not valid
DE_016	FAILURE	Month not valid
DE_017	FAILURE	Year not valid
DE_018	FAILURE	You can disburse the amount up to 6 months before from the current month
DE_019	FAILURE	MID is not valid
DE_020	FAILURE	Uploaded file is blank
DE_021	FAILURE	Disburse amount should be Rs. 1 or more
DE_023	FAILURE	Mid is not active
DE_026	FAILURE	Uploaded file must be of csv format
DE_027	FAILURE	File must contain 4 headers
DE_028	FAILURE	Cannot exceed columns more than <length>
DE_029	FAILURE	Total amount to be disbursed is more than the subwallet balance
DE_030	FAILURE	File already exists with this name
DE_034	FAILURE	Invalid Pay Mode
DE_035	FAILURE	Your request has been rejected by your configured Approver.
DE_036	FAILURE	Uploaded file contains records more than <param> records
DE_039	FAILURE	No record found
DE_040	FAILURE	Duplicate order id
DE_041	FAILURE	Unable to process your request. Please try after some time
DE_042	FAILURE	Date format is not correct as it should be yyyy-MM-dd
DE_057	FAILURE	Invalid request
DE_058	FAILURE	Merchant Commission not configured
DE_101	PENDING	Your request is in process. Kindly check after sometime
DE_400	FAILURE	Invalid Request Parameter
DE_401	FAILURE	Authentication Parameters Required
DE_402	FAILURE	Access Denied
DE_403	FAILURE	API Not Found
DE_404	FAILURE	Unable to authenticate the request
DE_405	FAILURE	Remote IP not whitelisted
DE_406	FAILURE	Invalid Client-Token
DE_407	FAILURE	Client-Token Required
DE_408	FAILURE	Checksum Required
DE_409	FAILURE	Checksum Verification Failed
DE_500	FAILURE	System Error
DE_609	FAILURE	Unable to fetch details
DE_633	FAILURE	Invalid amount
DE_634	FAILURE	Invalid transaction
DE_636	FAILURE	Unable to process
DE_646	FAILURE	Fund transfer not allowed for this transaction type
DE_647	FAILURE	Refund not allowed for this transaction type
DE_648	FAILURE	Product Service Unavailable
DE_701	FAILURE	Merchant does not exists
DE_702	FAILURE	User doesn't exist
DE_703	FAILURE	Wallet could not found, please verify walletGuid
DE_704	FAILURE	Sub wallet not found
DE_705	FAILURE	Agent wallet balance cann't be negative. Please fund your wallet and try again
DE_706	FAILURE	Refund is not possible as refund possibly already done or current refund request may cause refund to exceed actual transaction amount
DE_707	FAILURE	Refund amount should be equal to the transaction amount
DE_050	FAILURE	Callback URL passed is Invalid
DE_054	FAILURE	SubwalletGuid is not correct, Please check and try again
DE_055	FAILURE	Unable to disburse from given subWalletGuid. Please use another or create a new one
DE_648	QUEUED	Product Service Unavailable
DE_684	FAILURE	Credit adjustment
DE_702	FAILURE	User does not exist
DE_708	FAILURE	Sub wallet guid is not associated with this merchant
DE_709	FAILURE	Invalid Transaction Amount
DE_685	FAILURE	Fresh reversal
DE_686	FAILURE	Credit adjustment
DE_111	CANCELLED	Your order has been cancelled
DE_113	QUEUED	Your order is queued for next retry
DE_114	QUEUED	Your order is cancelled. Refund is initiated
DE_116	QUEUED	Your order is queued due to low balance in subwallet.
DE_065	FAILURE	Velocity limit exceeded
DE_1218	FAILURE	Could not find details for input beneficiary contactRefId
DE_1219	FAILURE	Could not fetch details for the contactRefId. Please try again
DE_064	FAILURE	Upfront commission not supported on this transaction. Please contact Merchant Helpdesk.
DE_1222	SUCCESS	Invalid wallet detail
DE_1223	SUCCESS	Wallet Limit exceeded
DE_1617	FAILURE	Schedule time format is not correct as it should be YYYY-MM-DD HH:MM:SS
DE_1618	FAILURE	Transactions can be scheduled after 1hr from now
DE_0618	PENDING	Your request is pending from Approver's end. Kindly check after sometime
DE_1623	FAILURE	Remitter name contains inappropriate word

Response Codes For Wallet Transfer

DE_001	SUCCESS	Successful disbursal to Wallet is done
DE_002	ACCEPTED	Request accepted
DE_010	FAILURE	parameter is mandatory and it's can't be null or blank
DE_011	FAILURE	parameter doesn't contain valid value
DE_012	FAILURE	An amount must be a positive number with maximal 2 decimal places
DE_013	FAILURE	param doesn't contain valid length, It should be <length> or less
DE_019	FAILURE	MID is not valid
DE_021	FAILURE	Disburse amount should be Rs. 1 or more
DE_023	FAILURE	Mid is not active
DE_034	FAILURE	Invalid Pay Mode
DE_039	FAILURE	No record found
DE_040	FAILURE	Duplicate order id
DE_041	FAILURE	Unable to process your request. Please try after some time
DE_044	FAILURE	Invalid beneficiary Mobile No. or Email Id
DE_045	FAILURE	Please provide either PhoneNo / Email Id
DE_046	FAILURE	Disbursal Date provided is not of valid format
DE_048	FAILURE	Phone No. not Registered
DE_049	FAILURE	Disburse amount should not be more than Rs. 100000
DE_101	PENDING	Your request is in process. Kindly check after sometime.
DE_103	FAILURE	Invalid Response Code
DE_104	FAILURE	PhoneNo. required to validate beneficiary name
DE_105	FAILURE	Beneficiary name not matched
DE_106	FAILURE	Mobile number is not registered
DE_107	FAILURE	KYC is Not Done
DE_108	FAILURE	Unable to validate Beneficiary Name
DE_400	FAILURE	Invalid Request Parameter
DE_401	FAILURE	Authentication Parameters Required
DE_402	FAILURE	Access Denied
DE_403	FAILURE	API Not Found
DE_404	FAILURE	Unable to authenticate request
DE_405	FAILURE	Remote IP not whitelisted
DE_406	FAILURE	Invalid Client-Token
DE_407	FAILURE	Client-Token Required
DE_408	FAILURE	Checksum Required
DE_409	FAILURE	Checksum Verification Failed
DE_500	FAILURE	System Error
DE_940	FAILURE	Invalid Txn Id
DE_901	FAILURE	Disbursal to wallet failed. Please try after sometime
DE_902	FAILURE	Disbursal to wallet failed
DE_961	FAILURE	Invalid user id
DE_919	FAILURE	Invalid merchant
DE_963	FAILURE	User exist but no corresponding wallet found
DE_964	FAILURE	Merchant exist but no corresponding wallet found
DE_906	FAILURE	Paytm wallet does not exist
DE_965	FAILURE	Found multiple accounts with same phone no. and all are unverified
DE_966	FAILURE	Found multiple accounts with same mail-id and all are unverified
DE_967	FAILURE	Merchant is incative
DE_921	FAILURE	Merchant does not exist
DE_922	FAILURE	Insufficient funds in corporate sub wallet
DE_931	FAILURE	Maximum allowed wallet balance is exceed
DE_948	FAILURE	Receiver has not completed his KYC
DE_932	FAILURE	Exceed maximum allowed money addition in wallet for this month
DE_933	FAILURE	RBI approved min KYC wallet spending limits exceeded. No new fund additions are allowed
DE_926	FAILURE	Maximum number of allowed transactions exceed
DE_947	FAILURE	RBI approved KYC wallet limits exceeded. No new fund additions are allowed
DE_924	FAILURE	Maximum allowed transaction amount exceed
DE_925	FAILURE	Max per transaction amount exceed
DE_969	FAILURE	Sales wallet not found
DE_907	FAILURE	Merchant can't transfer money to his own wallet
DE_970	FAILURE	Invalid salesWalletGuid
DE_971	FAILURE	Invalid salesWalletName/salesWalletGuid
DE_909	FAILURE	Payee mobile not verified
DE_910	FAILURE	Payee email not verified
DE_911	FAILURE	Payee mobile and email not verified
DE_972	FAILURE	Payer wallet could not found
DE_973	FAILURE	Adding funds to wallet not supported
DE_913	FAILURE	Sub Wallet not assigned to merchant
DE_974	FAILURE	Cashback Audit Details not available
DE_923	FAILURE	Paytm Wallet is not active
DE_975	FAILURE	Payer Wallet not active
DE_921	FAILURE	Merchant does not exist
DE_905	FAILURE	Corporate wallet not found
DE_908	FAILURE	Invalid userId, email or phone no.
DE_912	FAILURE	Adding funds to subwallet not supported
DE_914	FAILURE	Fund cannot be refilled in this wallet
DE_915	FAILURE	Funds cannot be added as user wallet type is basic
DE_916	FAILURE	SubWallet is not active
DE_917	FAILURE	Invalid Subwallet Expiry Date, Past expiry date is not allowed
DE_927	FAILURE	Maximum allowed transactions amount in a year exceed
DE_928	FAILURE	Maximum number of allowed transactions in a year exceed
DE_929	FAILURE	Cumulative txn type limit breached
DE_934	FAILURE	The destination Paytm user will need to do KYC to add/receive money
DE_935	FAILURE	Sub_Wallet limit exceeded
DE_936	FAILURE	Max Allowed sub wallet limit exceeded
DE_937	FAILURE	Maximum per transaction amount exceed
DE_941	FAILURE	Risk Reject
DE_943	FAILURE	Monthly limit for number of Payment to Merchant transactions will exceed
DE_944	FAILURE	Daily limit for total amount of Payment to Merchant transactions will exceed
DE_945	FAILURE	Monthly limit for total amount of Payment to Merchant transactions will exceed
DE_946	FAILURE	Daily limit for number of Payment to Merchant transactions will exceed
DE_949	FAILURE	Monthly credit limit breach
DE_978	FAILURE	Cashback PPIType is invalid
DE_979	FAILURE	PendingDaysLimit is out of range.
DE_983	FAILURE	You cannot add this amount as you will exceed wallet credit limit. Please try with a lower amount
DE_111	CANCELLED	Your order has been cancelled.
DE_116	QUEUED	Your order is queued due to low balance in subwallet.
DE_983	FAILURE	You cannot add this amount as you will exceed wallet credit limit. Please try with a lower amount
DE_976	PENDING	CashBack Pending!! Communication already sent to user
DE_1218	FAILURE	Could not find details for input beneficiary contactRefId
DE_1219	FAILURE	Could not fetch details for the contactRefId. Please try again
DE_1220	FAILURE	Multiple matches found for given beneficiary contactRefId
DE_047	FAILURE	Bank details not Registered
DE_064	FAILURE	Upfront commission not supported on this transaction. Please contact Merchant Helpdesk.
DE_1222	SUCCESS	Invalid wallet detail
DE_1223	SUCCESS	Wallet Limit exceeded
DE_1617	FAILURE	Schedule time format is not correct as it should be YYYY-MM-DD HH:MM:SS
DE_1618	FAILURE	Transactions can be scheduled after 1hr from now
DE_0618	PENDING	Your request is pending from Approver's end. Kindly check after sometime
DE_1623	FAILURE	Remitter name contains inappropriate word

⇾

Staging

Production

https://staging-dashboard.paytm.com/bpay/api/v2/beneficiary/validate copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://staging-dashboard.paytm.com/bpay/api/v2/beneficiary/validate' \
--header 'Content-Type: application/json' \
--header 'x-mid: {mid}' \
--header 'x-checksum: {checksum}' \
--data '{"subwalletGuid":"28054249-XXXX-XXXX-af8f-fa163e429e83","orderId":"ORDERID_98765", "beneficiaryPhoneNo":"800XXXX891"}'