Manage Mandates and Tokens
Track mandate funds, cancel tokens and delete tokens for UPI Reserve Pay (SBMD).
Once your UPI Reserve Pay integration is live, you can use the following APIs to monitor and manage active mandates.
Use the recurring_details object to monitor the utilisation of funds within an active mandate. This object is available in the response of the
Handy Tips
To find the remaining amount available for future debits, subtract the amount_debited from the amount_blocked. This allows you to manage customer expectations and ensure you do not initiate a debit that exceeds the remaining authorised limit.
The blocked amount under a UPI Reserve Pay token can be released in two ways:
Use the
below to release the blocked funds. When this API is called, all remaining funds under the token are unblocked and credited to the customer's bank account instantly.Released funds reflect in the customer's account instantly. The bank statement may not display this as a separate credit entry, but the account balance is updated immediately.
Handy Tips
Ensure customers are informed that their funds remain blocked until you explicitly release them or the token expires.
You can cancel tokens that are in the initiated, confirmed or paused state. Razorpay does not perform any additional validation checks before forwarding the cancellation request to NPCI.
Cancellations can fail if NPCI returns a failure response. This typically happens due to an internal issue on the remitter's side. Use the following endpoint to cancel a token. This initiates the cancellation of the mandate from NPCI.
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \-X PUT https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens/token_1Aa00000000001/cancel
Given below is a list of possible errors you may face while cancelling a token.
- Description: The token provided is not a recurring/autopay token and is not eligible for cancellation via this API.
- Next Steps: Please ensure you are passing a valid UPI Autopay recurring token. Non-recurring tokens cannot be cancelled using this API.
- Description: The UPI mandate linked to this token is not in a cancellable state. The mandate may already be revoked or failed.
- Next Steps: Please check the current status of the mandate before attempting cancellation. Cancellation is only allowed when the mandate is in confirmed or active state.
- Description: The token provided does not belong to the authenticated customer. Cross-customer token access is not permitted.
- Next Steps: Please verify that the
token_idbelongs to the customer in context and retry with the correct token.
- Description: The token provided was not created under your merchant account. Cross-merchant token access is not permitted.
- Next Steps: Please ensure you are using tokens created under your own merchant account and retry with the correct
token_id.
- Description: A cancellation or update operation is already in progress for this token. Simultaneous requests on the same token are not allowed.
- Next Steps: Please wait at least 60 seconds before retrying the cancellation request. Avoid sending duplicate or parallel cancel requests for the same token.
- Description: The cancellation request was received outside the allowed cancellation window or for an unsupported mandate type.
- Next Steps: Please ensure the cancel request is sent within the valid cancellation window and that the mandate type supports this operation. Retry after verifying mandate details.
Deleting a token removes it from Razorpay's database. The deleted token will not appear on the Dashboard or when all tokens are fetched. However, it does not cancel the mandate. If you wish to delete the mandate with Razorpay, you must first cancel it using the
.The following endpoint deletes a token.
customer_id
mandatory
string The unique identifier of the customer with whom the token is linked. For example, cust_1Aa00000000002.
token_id
mandatory
string The unique identifier of the token that is to be deleted. For example, token_1Aa00000000001.
Is this integration guide useful?