POSTBank Transfer API

Use Case

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

This API is used to disburse fund from sub-wallets/disbursal accounts to bank account using VPA / Mobile number / Bank account number and IFSC code.

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	It should be an alphanumeric, merchant’s unique reference ID for a disburse transaction passed in the request. This is Order ID for which the disburse order status needs to be fetched. Length should be 50 characters or less.
subwalletGuid string mandatory	Merchants sub wallet guid. Sub Wallet GUID is available on dashboard as "GUID".
amount string mandatory	Amount in INR payable by the merchant and it should contain digits up to two decimal points. The only special character allowed is (“.”). Amount limit from 1 to 2 Cr.
purpose string(50) mandatory	Pass any one from the below options: SALARY_DISBURSEMENT REIMBURSEMENT BONUS INCENTIVE OTHERS
date string(10) conditionally mandatory	Pass the date for which the merchant wants to disburse the amount. Required for SALARY_DISBURSEMENT and REIMBURSEMENT. Date format <YYYY-MM-DD>. Note: Mandatory if the "purpose" is Salary or Reimbursement
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 whose length should be 50 characters or below
transactionType string optional	Transaction Type is only applicable if transferMode is UPI. It can have the following Values: NON_CASHBACK - For all type of transactions except if you sending cashback to the end users CASHBACK - Send this value when you are sending cashback to end users By Default, NON_CASHBACK will be selected.
transferMode string(25) mandatory	Merchant can use this field to specify the disbursal mode. Pass any one from below: IMPS NEFT UPI RTGS
beneficiaryName string conditional	Beneficiary name is optional if transferMode is IMPS/UPI and mandatory if transferMode is NEFT and RTGS.
beneficiaryAccount string(19) mandatory	Bank account number of the beneficiary to which the disbursal should be made.
beneficiaryIFSC string(11) mandatory	IFSC code of the beneficiary account holding bank branch.
beneficiaryVPA string mandatory	VPA of the beneficiary to which the disbursal should be made
beneficiaryPhoneNo string mandatory	Phone No. of the beneficiary to which the disbursal should be made
beneficiaryContactRefId string mandatory	Unique identifier linked to the contact. Based on the Transfer mode, funds will be transferred to the default bank Account/ VPA for the Contact.

ATTRIBUTE

DESCRIPTION

orderId

string(50)
mandatory

It should be an alphanumeric, merchant’s unique reference ID for a disburse transaction passed in the request. This is Order ID for which the disburse order status needs to be fetched. Length should be 50 characters or less.

subwalletGuid

string
mandatory

Merchants sub wallet guid. Sub Wallet GUID is available on dashboard as "GUID".

amount

string
mandatory

Amount in INR payable by the merchant and it should contain digits up to two decimal points. The only special character allowed is (“.”). Amount limit from 1 to 2 Cr.

purpose

string(50)
mandatory

Pass any one from the below options:

SALARY_DISBURSEMENT
REIMBURSEMENT
BONUS
INCENTIVE
OTHERS

date

string(10)
conditionally mandatory

Pass the date for which the merchant wants to disburse the amount. Required for SALARY_DISBURSEMENT and REIMBURSEMENT. Date format <YYYY-MM-DD>.

Note: Mandatory if the "purpose" is Salary or Reimbursement

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 whose length should be 50 characters or below

transactionType

string
optional

Transaction Type is only applicable if transferMode is UPI. It can have the following Values:

NON_CASHBACK - For all type of transactions except if you sending cashback to the end users
CASHBACK - Send this value when you are sending cashback to end users

By Default, NON_CASHBACK will be selected.

transferMode

string(25)
mandatory

Merchant can use this field to specify the disbursal mode. Pass any one from below:

IMPS
NEFT
UPI
RTGS

beneficiaryName

string
conditional

Beneficiary name is optional if transferMode is IMPS/UPI and mandatory if transferMode is NEFT and RTGS.

beneficiaryAccount

string(19)
mandatory

Bank account number of the beneficiary to which the disbursal should be made.

beneficiaryIFSC

string(11)
mandatory

IFSC code of the beneficiary account holding bank branch.

beneficiaryVPA

string
mandatory

VPA of the beneficiary to which the disbursal should be made

beneficiaryPhoneNo

string
mandatory

Phone No. of the beneficiary to which the disbursal should be made

beneficiaryContactRefId

string
mandatory

Unique identifier linked to the contact. Based on the Transfer mode, funds will be transferred to the default bank Account/ VPA for the Contact.

Note:

For Transfer through IMPS, NEFT, RTGS Transfer mode you have to send either beneficiaryAccount & beneficiaryIFSC OR beneficiaryMID OR beneficiaryContactRefId in disbursal request.

For UPI Transfer, You have to choose anyone from beneficiaryVPA/ beneficiaryPhoneNo/ beneficiaryCustId/ beneficiaryContactRefId in disbursal request.

For Bank Reversal, please add Reversal Status Webhook on dashboard under the Developer Settings. Please click here for detailled documentation on Reversals. Pass anyone from beneficiaryVPA/ beneficiaryPhoneNo/ beneficiaryCustId/
beneficiaryAccount & beneficiaryIFSC/beneficiaryContactRefId 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.

Response Codes & Messages

statusCode	status	statusMessage
DE_001	SUCCESS	Successful disbursal to Bank Account 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	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_014	FAILURE	PPBL account no should be 12 digits and starts with 91.
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_022	FAILURE	Disburse amount should not be more than Rs. 200000.
DE_023	FAILURE	Mid is not active.
DE_024	FAILURE	Account no should be alphanumeric with length between 9 to 18 digits.
DE_025	FAILURE	IFSC code is invalid.
DE_026	FAILURE	Uploaded file must be of csv format
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_042	FAILURE	Date format is not correct as it should be yyyy-MM-dd.
DE_050	FAILURE	Callback URL passed is Invalid.
DE_051	FAILURE	Disbursal to other bank accounts not supported
DE_052	FAILURE	Bank Transfer Mode not valid
DE_053	FAILURE	IMPS not allowed for amount more than 2 lakhs
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_056	FAILURE	UPI not allowed for amount more than 1 lakhs
DE_057	FAILURE	Invalid request
DE_101	PENDING	Your request is in process. Kindly check after sometime.
DE_102	PENDING	Disbursal to Bank Account failed. Your refund to sub-wallet is in process.
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	FAILED	Remote IP not whitelist. Please ask your admin to whitelist Remote IP: <IP Address> from Payouts dashboard under developer's settings.
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_602	FAILURE	Disbursal to bank account failed. Please try after some time.
DE_603	FAILURE	Disbursal to bank account failed.
DE_604	PENDING	Disbursal to Bank Account is in process and pending at Beneficiary Bank.
DE_606	FAILURE	Invalid account number.
DE_607	FAILURE	Error at bank end.
DE_609	FAILURE	Unable to fetch details.
DE_612	FAILURE	Account blocked/frozen.
DE_613	FAILURE	Invalid IFSC/MICR.
DE_614	FAILURE	Account is closed.
DE_615	FAILURE	Invalid account number or IFSC code.
DE_616	FAILURE	Daily allowed amount limit for the beneficiary is exceeded.
DE_684	FAILURE	Credit adjustment
DE_617	FAILURE	Beneficiary account is NRE account.
DE_618	FAILURE	Invalid NBIN (IFSC code).
DE_619	FAILURE	NPCI rejects as net debit cap is exceeded for remitter.
DE_620	FAILURE	Card is restricted at beneficiary account.
DE_621	FAILURE	Transaction declined, Bank not enabled for P2A functionality.
DE_622	FAILURE	Maximum limit amount exceeded
DE_623	FAILURE	Exceeded maximum allowed number of transfers per day.
DE_625	FAILURE	Invalid IFSC code.
DE_640	FAILED	Transaction has been declined as it exceeds the limits set by beneficiary bank.
DE_626	FAILURE	Transaction is declined based on From account type and To account type.
DE_627	FAILURE	Transaction is declined based on transaction limit imposed on the From account type and To account type.
DE_628	FAILURE	Beneficiary PPI is Gift prepaid and this is not the first transaction.
DE_629	FAILURE	Acquiring bank has not implemented customer initiated person-to-merchant transaction.
DE_631	FAILURE	Amount is greater than 2 Lakhs (Applicable for Bank where NDC is greater than 2 Lakhs).
DE_632	FAILURE	Invalid payment reference.
DE_634	FAILURE	Invalid transaction.
DE_636	FAILURE	Unable to process.
DE_641	FAILURE	No record found.
DE_643	FAILURE	Remmiter and beneficiary accounts are same.
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_649	FAILURE	Transaction cannot be processed as current account limits will be breached.
DE_650	FAILURE	CA Form 60 Val Current Account Form 60 Daily deposit limit breached.
DE_651	FAILURE	Fraud verification Maquette suspicious response.
DE_652	FAILURE	Nodal IMPS Nodal IMPS Amount Limit Breached.
DE_653	FAILURE	Nodal IMPS Beneficiary Does Not exist.
DE_656	FAILURE	Credit account freeze.
DE_657	FAILURE	Host (CBS) offline / Beneficiary node offline
DE_658	FAILURE	Account does not exist in CBS
DE_659	FAILURE	Bank is not enabled for IMPS P2U
DE_660	FAILURE	This IFSC is no longer valid. Please update account details
DE_661	FAILURE	Invalid payee mobile
DE_662	FAILURE	Invalid virtual address
DE_663	FAILURE	Money transfer is not allowed to receiver account
DE_664	FAILURE	Money transfer request declined by the receiver bank. Please try again
DE_665	FAILURE	Payee bank UPI not supported
DE_666	FAILURE	Money transfer request declined by the remitter bank
DE_667	FAILURE	Bank account is not active
DE_668	FAILURE	UPI user not found
DE_669	FAILURE	UPI not registered or UPI registered but bank a/c not linked
DE_670	FAILURE	Your request was unsuccessful. Please try again
DE_671	FAILURE	You have exceeded the daily transaction amount limit set by your bank
DE_672	FAILURE	You can not send money to this UPI ID
DE_673	FAILURE	Invalid UPI id
DE_674	FAILURE	Beneficiary bank account details are not correct
DE_675	FAILURE	Something went wrong at the receiver bank servers. Please try again
DE_676	FAILURE	Beneficiary account does not exist
DE_677	FAILURE	Request declined by the receiver bank
DE_678	FAILURE	Invalid payer UPI address
DE_679	FAILURE	Beneficiary bank rejected as account type is not supported
DE_680	FAILURE	Beneficiary bank rejected credit for a reason. Eg: name missing/does not match
DE_681	FAILURE	User is not a Paytm UPI registered user
DE_601	PENDING	Disbursal to bank account is in process. Please check again in some time
DE_682	FAILURE	UPI VPA does not exist
DE_683	FAILURE	Money transfer declined by UPI payment service provider
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 can't be negative. Please fund your wallet and try again.
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_035	FAILURE	Your request has been rejected by your configured Approver.
DE_036	FAILURE	Uploaded file contains records more than <param> records
DE_043	FAILURE	Duplicate Account Number Found in the file
DE_058	FAILURE	Merchant Commission not configured
DE_065	FAILURE	Velocity limit exceeded
DE_110	FAILURE	VPA Validation Failed
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_610	FAILURE	No fds available
DE_633	FAILURE	Invalid amount
DE_637	FAILURE	Blocked/Lost/Hotlisted card
DE_638	FAILURE	Expired card
DE_639	FAILURE	Debit Request Failure
DE_654	FAILURE	Refund Processing Service No successful parent transaction found for request.
DE_655	FAILURE	Refund Processing service Refund amount is greater than max amount available for refund
DE_685	FAILURE	Fresh reversal
DE_686	FAILURE	Credit adjustment
DE_689	FAILURE	Inactive/Dormant Account
DE_690	FAILURE	Money transfer request declined by the receiver bank
DE_691	FAILED	Disbursal to bank account failed. Please try after some time.
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_708	FAILURE	Sub wallet guid is not associated with this merchant
DE_709	FAILURE	Invalid Transaction Amount
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_692	FAILURE	Beneficiary bank doe not allow transactions for lower amounts
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_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_687	SUCCESS	Wrong credit
DE_688	SUCCESS	Penalty Credit
DE_605	FAILURE	Transaction was rejected due to Risk threshold by NPCI/Beneficiary Bank
DE_611	FAILURE	Debit Card associated with beneficiary bank has expired. Please reach out to beneficiary bank
DE_630	FAILURE	Transaction deemed Failed
DE_624	FAILURE	Payee bank UPI not supported
DE_608	FAILURE	Per Transaction limit exceeded as set by the Beneficiary bank
DE_693	FAILURE	Transaction has been declined by NPCI / Beneficiary Bank due to risk policy
DE_694	FAILURE	Transaction has been declined as it exceeds the limits set by Remiiter bank.
DE_635	FAILURE	VPA length greater than 25 Characters
DE_642	FAILURE	Transaction not permitted on this account
DE_695	FAILURE	Transactions are rejected by beneficiary bank to this account
DE_696	FAILURE	VPA has Expired
DE_697	FAILURE	Collect Request on this VPA is Blocked
DE_698	FAILURE	Payment request was declined by the remitter bank as your account is invalid.
DE_801	FAILURE	Current account is out of balance
DE_802	FAILURE	Foreign inward remittance not allowed
DE_803	FAILURE	Invalid BC ID

⇾

Staging

Production

https://staging-dashboard.paytm.com/bpay/api/v1/disburse/order/bank copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://staging-dashboard.paytm.com/bpay/api/v1/disburse/order/bank' \
--header 'Content-Type: application/json' \
--header 'x-mid: {mid}' \
--header 'x-checksum: {checksum}' \
--data '{"subwalletGuid":"28054249-XXXX-XXXX-af8f-fa163e429e83","orderId":"ORDERID_98765","beneficiaryAccount":"918008484891","beneficiaryIFSC":"PYTM0123456","purpose":"SALARY_DISBURSEMENT","date":"2020-06-01","amount":"1.00"}'