POSTWallet Transfer API

Use Case

This API is used to disburse fund from sub-wallets/disbursal account to user wallets using the beneficiary mobile number or email Id.

Request URL

Following is a sample request URL which one can use: https://dashboard.paytm.com/bpay/api/v1/disburse/order/wallet/{solution}

Possible values of {solution} are: food, gift, gratification, loyalty, allowance, communication,fuel.

Inorder to use the request url please replace {solution} with any of the valid values.

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 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 Paytm checksum library.
Note: Create the signature using all the request parameters.

Request Attributes

API Content Type: JSON

ATTRIBUTE	DESCRIPTION
orderId string(50) mandatory	Unique reference ID provided by merchant using which each disbursal request is processed. This should be alphanumeric. Duplicate requests with the same orderId are rejected.
subwalletGuid string mandatory	Sub wallet/disbursal account GUID. This is available on Paytm dashboard
amount string mandatory	Amount in INR payable by the merchant. Should contain digits up to two decimal points. The only special character allowed is (“.”). Amount limit from 1 to 200000.
beneficiaryEmail OR beneficiaryPhoneNo string(50) mandatory	Customer Email id / Customer Phone Number against which the disbursal should be made.
validateBeneficiary boolean optional	Used to validate the beneficiary name. The field should be populated with 'true' value to process validation. Disbursal request is rejected if the name doesn't match with the name in Paytm system. The beneficiaryPhoneNo and beneficiaryName is mandatory for this to work.
beneficiaryName string(50) optional	Name of the customer to whom disbursal is being made. It is required if validateBeneficiary is passed as 'true'.
beneficiaryContactRefId string mandatory	The unique identifier linked to the contact. Based on the Transfer mode funds will be transferred to default bank Account/ VPA for the Contact.
callbackUrl string(255) optional	URL where we will post disbursal status. The merchant needs to whitelist this URL with Paytm.
comments string(50) optional	Disbursal comments.
disburseToNewUser boolean optional	If True, request is queued and email/sms is sent to user to register on Paytm to receive money. We auto send money post user registers or fail the request at end of days specified in maxQueueDays. By Default the Value will be True and maxQueueDays value is set to 3 days. This feature is only available for wallet gratification.
maxQueueDays int optional	Merchant can queue the request for below two cases. For new users For non KYC users if amount being transferred is outside non KYC permissible limits Pass 0 to not queue the request and fail immediately for such users. By Default maxQueueDays value is set to 3 days

Note: For UPI Transfer, You have to send transferMode as UPI and pass anyone from beneficiaryVPA or beneficiaryPhoneNo in disbursal request.

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	Disbursal request status. This attribute should be used to fetch the final status of the order. It can be FAILURE, ACCEPTED, SUCCESS, CANCELLED, PENDING, and QUEUED.
statusMessage string	Description of each statusCode.

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

Disbursal request status. This attribute should be used to fetch the final status of the order. It can be FAILURE, ACCEPTED, SUCCESS, CANCELLED, PENDING, and QUEUED.

statusMessage

string

Description of each statusCode.

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 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_111	CANCELLED	Your order has been cancelled.
DE_116	QUEUED	Your order is queued due to low balance in subwallet.
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_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_901	FAILURE	Disbursal to wallet failed. Please try after sometime.
DE_902	FAILURE	Disbursal to wallet failed.
DE_905	FAILURE	Corporate wallet not found.
DE_906	FAILURE	Paytm wallet does not exist.
DE_907	FAILURE	Merchant can't transfer money to his own wallet.
DE_908	FAILURE	Invalid userId, email or phone no.
DE_909	FAILURE	Payee mobile not verified.
DE_910	FAILURE	Payee email not verified.
DE_911	FAILURE	Payee mobile and email not verified.
DE_912	FAILURE	Adding funds to subwallet not supported.
DE_913	FAILURE	Sub Wallet not assigned to merchant.
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_919	FAILURE	Invalid merchant.
DE_921	FAILURE	Merchant does not exist.
DE_921	FAILURE	Merchant does not exist.
DE_922	FAILURE	Insufficient funds in corporate sub wallet.
DE_923	FAILURE	Paytm Wallet is not active.
DE_924	FAILURE	Maximum allowed transaction amount exceed.
DE_925	FAILURE	Max per transaction amount exceed.
DE_926	FAILURE	Maximum number of allowed transactions exceed.
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_931	FAILURE	Maximum allowed wallet balance is exceed.
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_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_940	FAILURE	Invalid Txn Id.
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_947	FAILURE	RBI approved KYC wallet limits exceeded. No new fund additions are allowed.
DE_948	FAILURE	Receiver has not completed his KYC.
DE_949	FAILURE	Monthly credit limit breach.
DE_961	FAILURE	Invalid user id.
DE_963	FAILURE	User exist but no corresponding wallet found.
DE_964	FAILURE	Merchant exist but no corresponding wallet found.
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_969	FAILURE	Sales wallet not found.
DE_970	FAILURE	Invalid salesWalletGuid.
DE_971	FAILURE	Invalid salesWalletName/salesWalletGuid.
DE_972	FAILURE	Payer wallet could not found.
DE_973	FAILURE	Adding funds to wallet not supported.
DE_974	FAILURE	Cashback Audit Details not available.
DE_975	FAILURE	Payer Wallet not active.
DE_976	PENDING	CashBack Pending!! Communication already sent to user
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_983	FAILURE	You cannot add this amount as you will exceed wallet credit limit. Please try with a lower amount
DE_047	FAILURE	Bank details not Registered.
DE_064	FAILURE	Upfront commission not supported on this transaction. Please contact Merchant Helpdesk.
DE_069	FAILURE	Maximum allowed monthly money transfer limit from your Paytm Payouts Account is exhausted. Monthly Limit - {param}
DE_1619	SCHEDULED	your order is scheduled.
DE_1217	FAILURE	Disburse amount should not be more than Rs. 10000
DE_1221	FAILURE	Not a valid paymode for Payout Link.
DE_1616	FAILURE	Expiry Date should be between current date and 10 years from current date only.
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.
DE_1700	FAILURE	Custom field with the key {param} is present more than once.
DE_1701	FAILURE	Custom field with the key {param} is mandatory.
DE_1702	FAILURE	Custom field with the key {param} is invalid.
DE_968	FAILURE	Duplicate reference id. Provide new reference id to process the refund.

⇾

Staging

Production

https://staging-dashboard.paytm.com/bpay/api/v1/disburse/order/wallet/{solution} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://staging-dashboard.paytm.com/bpay/api/v1/disburse/order/wallet/{solution}' \
--header 'Content-Type: application/json' \
--header 'x-mid: {mid}' \
--header 'x-checksum: {checksum}' \
--data '{"subwalletGuid":"28054249-XXXX-XXXX-af8f-fa163e429e83","orderId":"ORDERID_98765","beneficiaryPhoneNo":"5555566666","amount":"1.00"}'