JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Mandate Status

This API can be used by Merchant for checking the recent status of the mandate / (mandate action).

If merchantRequestId is not passed in the requestBody: Recent status of the mandate is denoted by gatewayResponseStatus field in the response. Based on different scenarios gatewayResponseStatus can have multiple values like SUCCESS, FAILURE, REVOKED, PAUSED, COMPLETED, DECLINED, EXPIRED depending upon the current status of the mandate.

If merchantRequestId is passed in the requestBody: Then gatewayResponseStatus denotes the status of that particular action (UPDATE, REVOKE, PAUSE and UNPAUSE) taken on mandate.

Refer to table below for different value of gatewayResponseCode and gatewayResponseStatus.

Scroll inside to view more

merchantRequestId in reqBody	gatewayResponseCode	gatewayResponseStatus	Description
Present	00	SUCCESS	Mandate is in active state
Present	01	PENDING	Mandate is in pending state
Present	JPMR	REVOKED	Mandate is revoked
Present	JPMP	PAUSE	Mandate is paused
Present	JPMC	COMPLETED	Mandate is completed
Present	JPMD	DECLINED	Mandate is declined by payer
Present	JPMX	EXPIRED	Mandate is expried due to no action by payer
Not Present	01	PENDING	Respective Mandate Action is in pending state
Not Present	00	SUCCESS	Corresponding Message for Mandate Action
Present / Not Present	Else	FAILURE	Any other reason.

Request

Response

API Endpoints

Production Link

POST

{{host}}/api/{{uri}}/merchants/mandates/status

                      jpupi-routing-id
                      *
                      

String

Mandatory

Header value should be same as of originalMerchantRequestId sent in request body

Body

                      role
                      *
                      

String

Mandatory

Defines the role of the merchant in the mandate.

Value: PAYEE.

                      originalMerchantRequestId
                      
                      

String

Optional But Mandatory For New Integration

Merchant request of the original create mandate request.

                      merchantRequestId
                      
                      

String

Condtional

Merchant generated unique id for the mandate action. To be used for update, revoke, pause, unpause operations.

Condition: Should be passed to know the status of the Mandate Action.

It should not be passed for create mandate status else BAD_REQUEST error will be thrown.

                      iat
                      *
                      

String

Mandatory

Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.

Example: 1496918882000.

                      udfParameters
                      
                      

Stringified JSON

optional

Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"

Note: Few special characters are not allowed. Regex for the characters which are not allowed : ^[^/#-()*!%~`]+$

Response Body

                      status
                      *
                      

String

Mandatory

PSP status of the API

Values:SUCCESS, FAILURE

                      responseCode
                      *
                      

String

Mandatory

PSP response code for the API.

Values: Refer Codes Guide in Resource Section.

                      responseMessage
                      *
                      

String

Mandatory

PSP response message for the API.

Values: Refer Codes Guide in Resource Section.

                      payload
                      *
                      

json

Mandatory

                      amount
                      *
                      

String

Mandatory

Amount for mandate

Values:Amount in two decimals. Decimals are mandatory

                      amountRule
                      *
                      

String

Mandatory

Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.

Values:As passed for amountRule in create mandate.

                      bankAccountUniqueId
                      
                      

String

optional

Unique id for the selected bank account. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.

Values: bankAccountUniqueId in the response of Fetch Accounts api call.

                      blockFund
                      *
                      

String

Mandatory

Denotes whether customer's fund should be blocked or not. True for recurring mandate, for ONETIME mandate can be true or false

Values:true / false

                      expiry
                      
                      

String

optional

Timestamp until which mandate request is valid. It will only be present if request is pending for approval for create mandate or update mandate.

Format:Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.

                      gatewayMandateId
                      *
                      

String

Mandatory

UPI request id returned by gateway for the particular mandate / mandate action request

                      gatewayReferenceId
                      *
                      

String

Mandatory

Customer reference number (rrn) for the mandate / mandate action operation.

                      gatewayResponseCode
                      *
                      

String

Mandatory

Response code returned by gateway for the mandate / mandate action operation.

Values:Refer table below.

                      gatewayResponseMessage
                      *
                      

String

Mandatory

Response message returned by gateway for the mandate / mandate action operation.

                      gatewayResponseStatus
                      *
                      

String

Mandatory

Denotes the current status of the mandate if upiRequestId is not passed in reqBody. Denotes the status of mandate action if upiRequestId is passed in reqBody.

Values:SUCCESS, FAILURE, PENDING, REVOKED, PAUSE, COMPLETED, DECLINED, EXPIRED

                      initiatedBy
                      *
                      

String

Mandatory

Defines who has initiated the mandate

Values:PAYER, PAYEE

                      mandateApprovalTimestamp
                      
                      

String

Optional

Time instant at which create mandate request was approved. Only present if mandate was initiatedBy PAYEE and upiRequestId is not passed in reqBody.

Format:YYYY-MM-DDTHH:MM:SS+05:30.

                      mandateName
                      *
                      

String

Mandatory

Name of the mandate

                      mandateTimestamp
                      *
                      

String

Mandatory

Timestamp of when the mandate / mandate action was initiated

Format:YYYY-MM-DDTHH:MM:SS+05:30

                      mandateType
                      *
                      

String

Mandatory

Defines the type of mandate operation

Values:CREATE, UPDATE, REVOKE, PAUSE, UNPAUSE

                      merchantChannelId
                      *
                      

String

Mandatory

Unique id for the merchant channel.

Values:As passed for x-merchant-channel-id in request headers.

                      merchantCustomerId
                      
                      

String

optional

Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.

Values:Alphanumeric string with dot(.). Maximum length is 256.

                      merchantId
                      *
                      

String

Mandatory

Unique id for the merchant.

Values:As passed for x-merchant-id in request headers

                      merchantRequestId
                      *
                      

String

Mandatory

Merchant generated unique id for collect request.

Constraint: Max 35 characters & Alphanumeric.

                      orgMandateId
                      *
                      

String

Mandatory

Refers to upiRequestId used during creation of mandate.

Values:Same as upiRequestId of create mandate.

                      pauseEnd
                      
                      

String

optional

Defines the date on which the mandate should unpause. It will only be present if mandateType is PAUSE, UNPAUSE.

Format: "YYYY/MM/DD".

                      pauseStart
                      
                      

String

optional

Defines the date from which the mandate should pause. It will only be present if mandateType is PAUSE, UNPAUSE.

Format: "YYYY/MM/DD".

                      payeeMcc
                      *
                      

String

Mandatory

Merchant Category Code of the payee merchant.

                      payeeName
                      
                      

String

optional

Name of the Payee involved in mandate. Only present if role is PAYER in request.

                      payeeVpa
                      *
                      

String

Mandatory

VPA of payee.

                      payerName
                      
                      

String

optional

Name of the Payer involved in mandate. Only present if role is PAYEE in request.

                      payerRevocable
                      *
                      

String

Mandatory

Defines whether mandate is revocable by PAYER or not. Applicable only when it is ONETIME mandate and initiatedBy PAYEE

                      payerVpa
                      *
                      

String

Mandatory

VPA of payer.

                      recurrencePattern
                      *
                      

String

Mandatory

Recurrence Pattern for Mandate.

Values:Same as original mandate in create mandate response.

                      recurrenceRule
                      
                      

String

optional

Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.

Values:Same as original mandate in create mandate response.

                      recurrencValue
                      
                      

String

optional

Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.

Values:Same as original mandate in create mandate response.

                      refUrl
                      *
                      

String

Mandatory

Invoice as sent by merchant or reference to the mandate in the form of url.

Values:String. As passed during creation of mandate.

                      remarks
                      *
                      

String

Mandatory

Any mandate summary

Values:As passed during create mandate response.

                      role
                      *
                      

String

Mandatory

Defines the role of the customer in the mandate.

Values:PAYER, PAYEE.

                      shareToPayee
                      *
                      

String

Mandatory

Descibes whether mandate will be shared with payee or not. Applicable only when it is ONETIME mandate and initiatedBy PAYER.

Values:String - true,false.

                      transactionType
                      *
                      

String

Mandatory

Type of Mandate Operation.

Values:UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE

umn

String

optional

Unique Mandate Number used for execution of the mandate. It will not be present if mandate is pending for payer's approval.

                      validityEnd
                      *
                      

String

Mandatory

Date before which mandate can be executed.

Format:YYYY/MM/DD.

                      validityStart
                      *
                      

String

Mandatory

Date after which mandate can be executed.

Format:YYYY/MM/DD.

                      originalMerchantRequestId
                      
                      

String

optional

Merchant Request Id of original mandate.

                      accountReferenceId
                      
                      

String

optional

Account ref id used for approving mandate.

                      gatewayTransactionId
                      
                      

String

optional

UPI request id returned by gateway for the transaction.

                      payerAccountHash
                      
                      

Array of String

optional

Hashed value of accounts to be passed by merchant for TPV.

                      recurrenceValue
                      
                      

String

optional

Recurrence Value for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.

                      tpvValidationStatus
                      
                      

String

optional

Value:FAILURE / SUCCESS

                      udfParameters
                      
                      

Stringified JSON

optional

Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"