API Reference

One Time Mandate

Overview

The One-Time Mandate (OTM) allows merchants to block funds from a customer's account for a specific period. Merchants can then either:

  • Capture those funds later (debit the money).

  • Release the blocked funds back to the customer.

This is required because there are scenarios where a delay is required(e.g., for processing or underwriting). “Juspay supports OTMs through the UPI payment method.”

How to Use the API for OTM

Merchants already integrated with mandates must update their integration to support OTM, based on their integration method:

  • Direct API Merchants: Add the required parameters in the Order/Session API request.

  • PP/SDK Merchants: Include these parameters in the SDK process payload.

  • Signature-Based Integrations: Ensure these parameters are part of the order details payload before signing.

Regardless of the integration method, the following parameters must be sent in API requests to initiate the OTM flow:

Scroll inside to view more
Parameter
Type
Description
mandate.block_funds
Boolean
Set to true to initiate the fund blocking process.
mandate.revokable_by_customer
Boolean
Set to false. The customer should not be able to revoke the mandate.
mandate.frequency
String
Set to ONETIME to indicate this is a one-time mandate for premiums/ subscription or any other use case.
mandate.start_date
Integer
The starting date of the mandate in Unix timestamp format (seconds). Use the current date.
mandate.end_date
Integer
The ending date of the mandate.

Session Response Parameters

Scroll inside to view more
Parameter
Type
Description
status
String
Status of the order. Can be NEW, PENDING, CHARGED, FAILED, etc.
id
String
Unique order ID generated by Juspay.
order_id
String
Your order ID.
payment_links.web
String
URL to the Juspay payment page.
sdk_payload
Object
Payload required for SDK integration (if applicable).
sdk_payload.requestId
String
Unique request ID for the SDK.
sdk_payload.payload
Object
Contains parameters for the payment page, including mandate details.
sdk_payload.payload.mandate.frequency
String
Indicates the frequency of the mandate, which is ONETIME.
sdk_payload.payload.firstName
String
The first name of the customer.
sdk_payload.payload.mandate.startDate
Integer
The start date of the mandate in Unix timestamp format (seconds).
sdk_payload.payload.clientId
String
The ID of the client merchant.
sdk_payload.payload.customerId
String
The ID of the customer.
sdk_payload.payload.orderId
String
The ID of the order.
sdk_payload.payload.returnUrl
String
The URL to redirect to after payment.
sdk_payload.payload.currency
String
The currency of the payment.
sdk_payload.payload.customerEmail
String
The email address of the customer.
sdk_payload.payload.customerPhone
String
The phone number of the customer.
sdk_payload.payload.service
String
Indicates the payment service used.
sdk_payload.payload.metadata.webhookUrl
String
The URL to send webhook notifications to.
sdk_payload.payload.description
String
A description of the payment.
sdk_payload.payload.options.createMandate
String
Indicates whether the creation of a mandate is optional or required.
sdk_payload.payload.mandate.blockFunds
Boolean
Indicates whether funds should be blocked.
sdk_payload.payload.mandate.revokableByCustomer
Boolean
Indicates whether the customer can revoke the mandate.
sdk_payload.payload.mandate.maxAmount
String
The maximum amount allowed for the mandate.
sdk_payload.payload.environment
String
The environment in which the payment is processed.
sdk_payload.payload.lastName
String
The last name of the customer.
sdk_payload.payload.timestamp
String
The timestamp of the payment request.
sdk_payload.payload.merchantId
String
The ID of the merchant.
sdk_payload.payload.amount
String
The amount of the payment.
sdk_payload.payload.clientAuthTokenExpiry
String
The expiration date and time of the client authentication token.
sdk_payload.payload.clientAuthToken
String
The client authentication token.
sdk_payload.payload.action
String
The action to be performed.
sdk_payload.payload.mandate.endDate
Integer
The end date of the mandate.

Batch Mandates

Merchants can process One-Time Mandates (OTM) in bulk using the Batch Mandate feature. This allows multiple mandates to be initiated in a single request, streamlining operations and reducing API calls.

For detailed guidelines Refer to Batch Mandates Documentationlink icon

Note

This feature, like all mandates, is only available for registered customers and does not support guest checkouts.

Webhooks and Order Status

When an OTM is created, the following additional fields must be included in the mandate block within webhook notifications and order status updates:

Scroll inside to view more
Parameter
Value
block_fund
TRUE
revokable_by_customer
FALSE
frequency
ONETIME
Note

Merchants must validate the presence and values of these fields in order status updates for accurate OTM processing.

Mandate Block/ Order Amount Response

Also, note these amount-related fields:

  • maximum_eligible_refund_amount, amount, and effective_amount will be equal to mandate.max_amount.

  • amount_debited will be the amount actually captured (which might be less than mandate.max_amount if you only capture part of the blocked amount).

Post-Registration Flows

Mandate Execution

Use the Mandate Execution API to debit the blocked funds after successful mandate registration. This ensures that the payment is processed as per the predefined mandate conditions.

  • This action can be performed via API or directly from the Juspay dashboard.

    Note

    Notifications are not required for one-time mandates (OTM) on UPI. Therefore, notification-related parameters should not be included in the Mandate Execution API request.

Mandate Revoke

The Mandate Revoke API allows merchants to revoke an existing mandate before it is executed. This may be necessary if the user withdraws consent or if the service is no longer required.

  • Merchants can revoke a mandate through the API or via the Juspay dashboard.

  • Once revoked, the blocked funds will be released back to the user’s account.

    Refer to API Specslink icon

Mandate Update

Mandates can be updated under certain conditions.

  • Changes can be made to update the mandate; however, explicit customer consent is required before modifying the mandate amount.

  • Updates are subject to the availability of this feature at the Payment Gateway (PG) level.

    Refer to API Specslink icon

Auto-Release

If the mandate isn’t executed before mandate.end_date, funds auto-release to the user.

  • A mandate revoke webhook will trigger upon expiry.

  • The timeframe for auto-revocation may vary based on industry regulations and use case requirements.

    • For example, in the insurance sector, mandates are typically auto-revoked after 14 days if not utilized.

Dashboard Configuration

Step 1
Configuring a Gateway
Step 2
Payment Method Configuration
Step 3
eMandate setting
Step 4
Repeat
OTM Configuration
OTM Configuration

Supported Gateways:

Scroll inside to view more
Gateway
Current Stage
AXIS_BIZ
Live
YES_BIZ
Live
RBL_BIZ
Live
PayU
Live
BILLDESK
Integration Phase
ICICI_UPI
Integration Phase
Cashfree
Integration Phase
CAMSpay
Integration Phase

Supported PSP Handles

At present we support the below listed PSP’s

Scroll inside to view more
PSP Handle
PSP Handle
PSP Handle
PSP Handle
@ybl
@paytm
@upi
@ibl
@axl
@boi
@cnrb
@okhdfcbank
@okaxis
@axisbank
@postbank
@ikwik
@barodampay
@apl
@indus
@dbs
@icici
@okicici
@dlb
@sliceaxis
@pz
@jio
@sbi
@axb
@yesg
@yapl
@pnb
@oksbi
@jupiteraxis
@shriramhdfcbank
@abfspay
@niyoicici
@waicici
@centralbank
@equitas
@naviaxis
@ypay
@axispay
@razorpay
@tapicici
@Goaxb
@mahb
@fincarebank
@iob
@indie
@pingpay
@yespay
@gocash
@kotak
@kotak811
@paytmwallet
@axisb
@freecharge
@hdfcbank
@abcdicici
@sbipa
@fifederal
@Payu
@timecosmos
@sib
@ptyes
@ptaxis
@ptsbi
@pthdfc
@oneyes
@seyes
@superyes
@ttyes
@yescurie
@yesfam
@yestp
@gwaxis
@rmrbl
@easebuzz

FAQ’s

Is partial capture of the blocked amount possible?

What happens to the remaining blocked amount?

Note

For assistance, contact Juspay @ support@juspay.in

Last updated 1 year ago