search

POSTWallet Transfer API

Use Case

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: foodgiftgratificationloyaltyallowancecommunication,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.

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.
  1. For new users
  2. 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. It can be FAILURE, ACCEPTED, SUCCESS, CANCELLED and QUEUED.

statusMessage

string

Description of each statusCode.

Response Codes & Messages

statusstatusCodestatusMessage
DE_001SUCCESSSuccessful disbursal to Wallet is done.
DE_002ACCEPTEDRequest accepted.
DE_010FAILUREparameter 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
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"}'
copy icon