search

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.

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.

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.

Response Codes & Messages

statusCodestatusstatusMessage
DE_001SUCCESSSuccessful disbursal to Bank Account is done.
DE_002ACCEPTEDRequest accepted.
DE_010FAILUREparameter is mandatory and it's can't be null or blank.
DE_011FAILUREparameter doesn't contain valid value.
DE_012FAILUREAmount must be a positive number with maximal 2 decimal places.
DE_013FAILUREParam doesn't contain valid length, It should be <length> or less.
DE_014FAILUREPPBL account no should be 12 digits and starts with 91.
DE_015FAILUREPurpose not valid.
DE_016FAILUREMonth not valid.
DE_017FAILUREYear not valid.
DE_018FAILUREYou can disburse the amount up to 6 months before from the current month.
DE_019FAILUREMID is not valid.
DE_020FAILUREUploaded file is blank
DE_021FAILUREDisburse amount should be Rs. 1 or more.
DE_022FAILUREDisburse amount should not be more than Rs. 200000.
DE_023FAILUREMid is not active.
DE_024FAILUREAccount no should be alphanumeric with length between 9 to 18 digits.
DE_025FAILUREIFSC code is invalid.
DE_026FAILUREUploaded file must be of csv format
DE_034FAILUREInvalid Pay Mode.
DE_039FAILURENo record found.
DE_040FAILUREDuplicate order id.
DE_041FAILUREUnable to process your request. Please try after some time.
DE_042FAILUREDate format is not correct as it should be yyyy-MM-dd.
DE_050FAILURECallback URL passed is Invalid.
DE_051FAILUREDisbursal to other bank accounts not supported
DE_052FAILUREBank Transfer Mode not valid
DE_053FAILUREIMPS not allowed for amount more than 2 lakhs
DE_054FAILURESubwalletGuid is not correct, Please check and try again
DE_055FAILUREUnable to disburse from given subWalletGuid. Please use another or create a new one
DE_056FAILUREUPI not allowed for amount more than 1 lakhs
DE_057FAILUREInvalid request
DE_101PENDINGYour request is in process. Kindly check after sometime.
DE_102PENDINGDisbursal to Bank Account failed. Your refund to sub-wallet is in process.
DE_400FAILUREInvalid Request Parameter.
DE_401FAILUREAuthentication Parameters Required.
DE_402FAILUREAccess Denied.
DE_403FAILUREAPI Not Found.
DE_404FAILUREUnable to authenticate request.
DE_405FAILEDRemote IP not whitelist. Please ask your admin to whitelist Remote IP: <IP Address> from Payouts dashboard under developer's settings.
DE_406FAILUREInvalid Client-Token.
DE_407FAILUREClient-Token Required.
DE_408FAILUREChecksum Required.
DE_409FAILUREChecksum Verification Failed.
DE_500FAILURESystem Error.
DE_602FAILUREDisbursal to bank account failed. Please try after some time.
DE_603FAILUREDisbursal to bank account failed.
DE_604PENDINGDisbursal to Bank Account is in process and pending at Beneficiary Bank.
DE_606FAILURE Invalid account number.
DE_607FAILUREError at bank end.
DE_609FAILUREUnable to fetch details.
DE_612FAILUREAccount blocked/frozen.
DE_613FAILUREInvalid IFSC/MICR.
DE_614FAILUREAccount is closed.
DE_615FAILUREInvalid account number or IFSC code.
DE_616FAILUREDaily allowed amount limit for the beneficiary is exceeded.
DE_684FAILURECredit adjustment
DE_617FAILUREBeneficiary account is NRE account.
DE_618FAILUREInvalid NBIN (IFSC code).
DE_619FAILURENPCI rejects as net debit cap is exceeded for remitter.
DE_620FAILURECard is restricted at beneficiary account.
DE_621FAILURETransaction declined, Bank not enabled for P2A functionality.
DE_622FAILUREMaximum limit amount exceeded
DE_623FAILUREExceeded maximum allowed number of transfers per day.
DE_625FAILUREInvalid IFSC code.
DE_640FAILEDTransaction has been declined as it exceeds the limits set by beneficiary bank.
DE_626FAILURETransaction is declined based on From account type and To account type.
DE_627FAILURETransaction is declined based on transaction limit imposed on the From account type and To account type.
DE_628FAILUREBeneficiary PPI is Gift prepaid and this is not the first transaction.
DE_629FAILUREAcquiring bank has not implemented customer initiated person-to-merchant transaction.
DE_631FAILUREAmount is greater than 2 Lakhs (Applicable for Bank where NDC is greater than 2 Lakhs).
DE_632FAILUREInvalid payment reference.
DE_634FAILUREInvalid transaction.
DE_636FAILUREUnable to process.
DE_641FAILURENo record found.
DE_643FAILURERemmiter and beneficiary accounts are same.
DE_646FAILUREFund transfer not allowed for this transaction type.
DE_647FAILURERefund not allowed for this transaction type.
DE_648FAILUREProduct Service Unavailable.
DE_649FAILURETransaction cannot be processed as current account limits will be breached.
DE_650FAILURECA Form 60 Val Current Account Form 60 Daily deposit limit breached.
DE_651FAILUREFraud verification Maquette suspicious response.
DE_652FAILURENodal IMPS Nodal IMPS Amount Limit Breached.
DE_653FAILURENodal IMPS Beneficiary Does Not exist.
DE_656FAILURECredit account freeze.
DE_657FAILUREHost (CBS) offline / Beneficiary node offline
DE_658FAILUREAccount does not exist in CBS
DE_659FAILUREBank is not enabled for IMPS P2U
DE_660FAILUREThis IFSC is no longer valid. Please update account details
DE_661FAILUREInvalid payee mobile
DE_662FAILUREInvalid virtual address
DE_663FAILUREMoney transfer is not allowed to receiver account
DE_664FAILUREMoney transfer request declined by the receiver bank. Please try again
DE_665FAILUREPayee bank UPI not supported
DE_666FAILUREMoney transfer request declined by the remitter bank
DE_667FAILUREBank account is not active
DE_668FAILUREUPI user not found
DE_669FAILUREUPI not registered or UPI registered but bank a/c not linked
DE_670FAILUREYour request was unsuccessful. Please try again
DE_671FAILUREYou have exceeded the daily transaction amount limit set by your bank
DE_672FAILUREYou can not send money to this UPI ID
DE_673FAILUREInvalid UPI id
DE_674FAILUREBeneficiary bank account details are not correct
DE_675FAILURESomething went wrong at the receiver bank servers. Please try again
DE_676FAILUREBeneficiary account does not exist
DE_677FAILURERequest declined by the receiver bank
DE_678FAILUREInvalid payer UPI address
DE_679FAILUREBeneficiary bank rejected as account type is not supported
DE_680FAILUREBeneficiary bank rejected credit for a reason. Eg: name missing/does not match
DE_681FAILUREUser is not a Paytm UPI registered user
DE_601PENDINGDisbursal to bank account is in process. Please check again in some time
DE_682FAILUREUPI VPA does not exist
DE_683FAILUREMoney transfer declined by UPI payment service provider
DE_701FAILUREMerchant does not exists.
DE_702FAILUREUser doesn't exist
DE_703FAILUREWallet could not found, please verify walletGuid.
DE_704FAILURESub wallet not found.
DE_705FAILUREAgent wallet balance can't be negative. Please fund your wallet and try again.
DE_027FAILUREFile must contain 4 headers
DE_028FAILURECannot exceed columns more than <length>
DE_029FAILURETotal amount to be disbursed is more than the subwallet balance
DE_030FAILUREFile already exists with this name
DE_035FAILUREYour request has been rejected by your configured Approver.
DE_036FAILUREUploaded file contains records more than <param> records
DE_043FAILUREDuplicate Account Number Found in the file
DE_058FAILUREMerchant Commission not configured
DE_065FAILUREVelocity limit exceeded
DE_110 FAILUREVPA Validation Failed
DE_111CANCELLEDYour order has been cancelled
DE_113QUEUEDYour order is queued for next retry
DE_114QUEUEDYour order is cancelled. Refund is initiated
DE_116QUEUEDYour order is queued due to low balance in subwallet.
DE_610FAILURENo fds available
DE_633FAILUREInvalid amount
DE_637FAILUREBlocked/Lost/Hotlisted card
DE_638FAILUREExpired card
DE_639FAILUREDebit Request Failure
DE_654FAILURERefund Processing Service No successful parent transaction found for request.
DE_655FAILURERefund Processing service Refund amount is greater than max amount available for refund
DE_685FAILUREFresh reversal
DE_686FAILURECredit adjustment
DE_689FAILUREInactive/Dormant Account
DE_690FAILUREMoney transfer request declined by the receiver bank
DE_691FAILEDDisbursal to bank account failed. Please try after some time.
DE_706FAILURERefund is not possible as refund possibly already done or current refund request may cause refund to exceed actual transaction amount
DE_707FAILURERefund amount should be equal to the transaction amount
DE_708FAILURESub wallet guid is not associated with this merchant
DE_709FAILUREInvalid Transaction Amount
DE_1218FAILURECould not find details for input beneficiary contactRefId
DE_1219FAILURECould not fetch details for the contactRefId. Please try again
DE_1220FAILUREMultiple matches found for given beneficiary contactRefId
DE_692FAILUREBeneficiary bank doe not allow transactions for lower amounts
DE_047FAILUREBank details not Registered
DE_064FAILUREUpfront commission not supported on this transaction. Please contact Merchant Helpdesk.
DE_069FAILUREMaximum allowed monthly money transfer limit from your Paytm Payouts Account is exhausted. Monthly Limit - {param}
DE_1619SCHEDULEDyour order is scheduled
DE_1617FAILURESchedule time format is not correct as it should be YYYY-MM-DD HH:MM:SS
DE_1618FAILURETransactions can be scheduled after 1hr from now
DE_0618PENDINGYour request is pending from Approver's end. Kindly check after sometime
DE_1623FAILURERemitter name contains inappropriate word
DE_1700FAILURECustom field with the key {param} is present more than once.
DE_1701FAILURECustom field with the key {param} is mandatory.
DE_1702FAILURECustom field with the key {param} is invalid
DE_687SUCCESSWrong credit
DE_688SUCCESSPenalty Credit
DE_605FAILURETransaction was rejected due to Risk threshold by NPCI/Beneficiary Bank
DE_611FAILUREDebit Card associated with beneficiary bank has expired. Please reach out to beneficiary bank
DE_630FAILURETransaction deemed Failed
DE_624FAILUREPayee bank UPI not supported
DE_608FAILUREPer Transaction limit exceeded as set by the Beneficiary bank
DE_693FAILURETransaction has been declined by NPCI / Beneficiary Bank due to risk policy
DE_694FAILURETransaction has been declined as it exceeds the limits set by Remiiter bank.
DE_635FAILUREVPA length greater than 25 Characters
DE_642FAILURETransaction not permitted on this account
DE_695FAILURETransactions are rejected by beneficiary bank to this account
DE_696FAILUREVPA has Expired
DE_697FAILURECollect Request on this VPA is Blocked
DE_698FAILUREPayment request was declined by the remitter bank as your account is invalid.
DE_801FAILURECurrent account is out of balance
DE_802FAILUREForeign inward remittance not allowed
DE_803FAILUREInvalid BC ID
⇾
Staging
Production
https://staging-dashboard.paytm.com/bpay/api/v1/disburse/order/bankcopy 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"}'
copy icon