1. Introduction

A mandate can be edited in case there is a change in any attributes of the mandate previously set. Alternately, a Mandate which has been set can also be deleted if desired by the customer. Both these actions require a consent from the customer. BillDesk's Neo – Full Redirect lets merchants offer both these options conveniently to customers.

2. Integration Steps

Depending on the workflows mentioned above, the steps to Integrate vary and have been outlined below:

Step 1: Create a Mandate token

An mandate token needs to be created for every mandate to be edited using the BillDesk Neo – Full Redirect.

To edit a mandate, use the Modify Mandate Token API. This API has an attribute of action which can take values of modify or delete depending on the action to be taken for the mandate. The response of this API provides the mandate_tokenid, href & rdata values required to launch the BillDesk Neo – Full Redirect (explained in Step 2).

Attribute	Description
mercid	Unique identifier provided by BillDesk for each merchant.
href	This is the URL on which the required parameters need to be posted to BillDesk to launch the BillDesk Neo – Full Redirect. `UAT`- https://uat1.billdesk.com/u2/web/v1_2/sdk `Production`- https://pay.billdesk.com/web/v1_2/sdk
rdata	Value generated by BillDesk in the “links” object of the Modify Mandate Token API. Please refer to the response of the Create Mandate Token API provided below. The links objects too is available separately.
mandate_tokenid	Value generated by BillDesk in the Modify Mandate Token API response.

{
	"objectid": "mandate_token",
	"mandate_tokenid": "NA0D080090483",
	"mandateid": "MA0ED20005573",
	"mercid": "BDMERCID",
	"customer_refid": "cus890987067792335",
	"subscription_refid": "12345678901234535",
	"subscription_desc": "Hola",
	"start_date": "2023-06-09",
	"end_date": "2026-12-23",
	"amount": "200.10",
	"amount_type": "maximum",
	"currency": "356",
	"frequency": "adho",
	"createdon": "2023-08-20T13:07:02+05:30",
	"ru": "http://localhost:3000/api/pgresponse/modal/redirect",
	"additional_info": {
		"additional_info1":"Details1",
    "additional_info2":"Details2",
    "additional_info3":"NA",
    "additional_info4":"NA",
    "additional_info5":"NA",
    "additional_info6":"NA",
    "additional_info7":"NA"
	},
	"customer": {
		"customer_refid": "cus890987067792335"
	},
	"device": {
		"fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19",
		"init_channel": "internet",
		"ip": "192.168.1.1",
		"user_agent": "Mozilla/Firefox",
		"accept_header": "text/html"
	},
	"status": "initiated",
	"action": "modify",
	"payment_method_type": "card",
	"mandate_edit": {
		"amount": "1000.00"
	},
	"next_step": "redirect",
	"links": [
		{
			"href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate",
			"rel": "self",
			"method": "POST",
			"parameters": null,
			"valid_date": null,
			"headers": null
		},
		{
			"href": " https://www.sampleurl.com/sdk/",
			"rel": "redirect",
			"method": "POST",
			"parameters": {
				"mercid": "BDMERCID",
				"mandate_tokenid": "NA0D0800060183",
				"rdata": "89fd934cf8ca5f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			},
			"valid_date": "2023-08-20T13:37:02+05:30",
			"headers": {
				"authorization": "OToken 18183EEED380A39203B26A9230F41F0B20943A2F3045318060C2ED64 9E63BCA26F29BB9EF86987E7A5BBD4241ADF 9F83A19E90E37E296BD92EC0588565D1C15FE599E4178E94C097BBF2 5FA2B85B3ED89BB5CD0966FCEF320A8DB82B80BCF5241A5C50382A79 FFBD6338C5D46C4836853E0A26.4145535F55415431"
			}
		}
	]
}

{
	"links": [
		{
			"href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/ini tiate",
			"rel": "self",
			"method": "POST",
			"parameters": null,
			"valid_date": null,
			"headers": null
		},
		{
			"href": " https://www.sampleurl.com/sdk/",
			"rel": "redirect",
			"method": "POST",
			"parameters": {
				"mercid": "BDMERCID",
				"mandate_tokenid": "NA0D0800060183",
				"rdata": "89fd934cf8ca5f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			},
			"valid_date": "2023-08-20T13:37:02+05:30",
			"headers": {
				"authorization": "OToken 18183EEED380A39203B26A9230F41F0B20943A2F3045318060C2ED64 9E63BCA26F29BB9EF86987E7A5BBD4241ADF 9F83A19E90E37E296BD92EC0588565D1C15FE599E4178E94C097BBF2 5FA2B85B3ED89BB5CD0966FCEF320A8DB82B80BCF5241A5C50382A79 FFBD6338C5D46C4836853E0A26.4145535F55415431"
			}
		}
	]
}

💬
Preparing a request payload
Every API Request needs to encrypted. Similarly the Response of each API is also returned in an encrypted format by BillDesk.
A step by step guide to prepare the request payload, transmit it and capture the response is available here.

💬
Validity of a mandate token
Every mandate token created with the Update Mandate Token API is valid for a period of 30 minutes. This would mean that the customer needs to modify or delete the mandate in this timeframe.

Step 2: Launch the BillDesk Neo – Full Redirect

To launch the page, merchant would need to POST a form with attributes received from the Modify Mandate Token API(Step 1).

Sample Form

<html>
	<head></head>
	<body>
		<form name="sdklaunch" id="sdklaunch" action="<URL for UAT/ Production. Refer Step 1>" method="POST">
		<input type="hidden" id="merchantId" name="merchantId" value="BDMERCID" />
		<input type="hidden" id="mandateTokenId" name="mandateTokenId" value="TSFFDHWE" />
    <input type="hidden" id="rdata" name="rdata" value= "89fd934cf8ca5ad76b8efbcf1d56caf8546a28d5b7876ad0f4070d4.70675f706172616d5"> 
		<input name="submit" type="submit" value="Edit the Mandate" />
		</form>
	</body>
</html>

Step 3: Capture the mandate response

Once the mandate setup has been completed by the customer using a payment method of choice, the customer is returned to the "ru" attribute provided in the Modify Mandate Token API. BillDesk will also POST a response to this URL containing details of the mandate.

Capture and parse the mandate response
The transaction response provided depends on the payment method used by the customer. (Samples provided below):
The value after the mandate_response parameter till the next "&" character is the encrypted mandate response which provides more details about the mandate which has been set up. A step by step guide on how to decrypt the mandate_response parameter is available here.

A) For action "modify"

terminal_state=Y&mandate_tokenid=NN054919682783&mandate_response=eyJhbGciOiJIUzI1NiIsImNsaWVudGlkIjoiYmRobWFjdGVzdCIsImtpZCI6IkhNQUMifQ.eyJtYW5kYXRlaWQiOiJNTjExNkExNTcwNDU2OTIiLCJ2ZXJpZmljYXRpb25fZXJyb3JfY29kZSI6Ik1OUzAwMDAiLCJ2ZXJpZmljYXRpb25fZXJyb3JftHlwZSI6InN1Y2Olc3MiLCJjcmVhdGVkb24iOiIyMDI0LTAyLTI2VDE3OjA4OjI2KzA1OjMwIiwidmVyaWZpY2F0aW9uX2Vycm9yX2Rlc2MiOiJNYW5kYXRlIFN1Y2Nlc3NmdWwiLCJzdGF0dXMiOiJERUxFVEVEIn0.Ffm1e-HwKW2-wkG3NIlsvC06lY2M5CCBjMhvGZ1lTv4&keyid=HMAC&objectid=mandate

mandate_response=eyJhbGciOiJIUzI1NiIsImNsaWVudGlkIjoiYmRobWFjdGVzdCIsImtpZCI6IkhNQUMifQ.eyJtZXJjaWQiOiJWMkJETU9OMSIsImVuZF9kYXRlIjoiMjAyNi0wOC0yMCIsInBheW1lbnRfbWV0aG9kX3R5cGUiOiJjYXJkIiwiYW1vdW50IjoiMTAuMDAiLCJydSI6Imh0dHBzOi8vd3d3Lm1lcmNoYW50dXJsLmNvbS9yZXNwb25zZS5qc3AiOCJzdWJzY3JpcHRpb25fZGVzYyI6IkFWU2RodmZpYmZmeXVlcmZ0aW5laXUiLCJ2ZXJpZmljYXRpb25fZXJyb3JfdHlwZSI6InN1Y2Nlc3MiLCJjcmVhdGVkb24iOiIyMDI0LTAyLTI2VDE3OjIyOjI1KzA1OjMwIiwiYmFua191bXJuIjoiWDVuZkxLNjlQWSIsInRyYW5zYWN0aW9uaWQiOiJNVDBCRUUxMjM3ODUzMTYiLCJmcmVxdWVuY3kiOiJ3ZWVrIiwiY3VzdG9tZXJfcmVmaWQiOiJjdXN0ZmVmYmZydCIsImFtb3VudF90eXBlIjoiZml4ZWQiLCJtYW5kYXRlaWQiOiJNTjI1OTIxNTcwNTEzMjYiLCJ2ZXJpZmljYXRpb25fZXJyb3JfY29kZSI6IlRSUzAwMDAiLCJzdWJzY3JpcHRpb25fcmVmaWQiOiJTdWhmYmZiZmZydCIsImN1cnJlbmN5IjoiMzU2Iiwib2JqZWN0arQiOiJtYW5kYXRlIiwiY2FyZCI6eyJjYXJkYWNjb3VudGlkIjoiQ0EwNTJCRjAwMDAwMzgyMTA2NTkiLCJjYXJkX2VuZCI6IjI0MjYiLCJwYXltZW50YWNjb3VudGlkIjoiUEEwMzg1MTU0NjM1MDk5IiwidHlwZSI6IkNSRURJVCIsImlzc3VlciI6IlllcyBCYW5rIiwibWFza2VkX3ZhbHVlIjoieHh4eHh4eHh4eHh4MjQyNiIsImhvbGRlcl9uYW1lIjoiQXJqdW4iLCJuZXR3b3JrIjoiTUFTVEVSIn0sInZlcmlmaWNhdGlvbl9lcnJvcl9kZXNjIjoiVHJhbnNhY3Rpb24gU3VjY2Vzc2Z1bCIsInN0YXJ0X2RhdGUiOiIyMDI0LTAyLTI2Iiwic3RhdHVzIjoiYWN0aXZlIiwiY3VzdG9tZXIiOnt9fQ.0fykNu0ejqWZLav2ZwK870RU8TWLZIPV4-U9r-kSOpk&mandate_tokenid=NN019619689991

{
"objectid":"mandate",
"mandateid":"MN10A1157059143",
"mercid":"BDMERCID",
"customer_refid":"custfefbffrt",
"subscription_refid":"Suhfbfbfffrt",
"subscription_desc":"AVSdhvfibfffyuerftineiu",
"start_date":"2024-02-26",
"end_date":"2026-08-20",
"amount":"10.00",
"amount_type":"fixed",
"currency":"356",
"frequency":"week",
"status":"active",
"createdon":"2024-02-26T18:06:04+05:30",
"payment_method_type":"upi",
"ru":"https://www.merchanturl.com/response.jsp",
"upi":{
"paymentaccountid":"PA0F85154641897",
"vpa":"john.doe@okaxis",
"psp":"okaxis"
},
"customer":{

},
"verification_error_code":"MNS0000",
"verification_error_type":"success",
"verification_error_desc":"Mandate Successful",
"recurrence_rule":"after",
"debit_day":"1",
"bank_umrn":"d70703bc54ec42fb9eb80d75d69ac21d@okaxis"
}

{
"objectid":"mandate",
"mandateid":"MN2592157051326",
"mercid":"BDMERCID",
"customer_refid":"custfefbfrt",
"subscription_refid":"Suhfbfbffrt",
"subscription_desc":"AVSdhvfibffyuerftineiu",
"start_date":"2024-02-26",
"end_date":"2026-08-20",
"amount":"10.00",
"amount_type":"fixed",
"currency":"356",
"frequency":"week",
"status":"active",
"createdon":"2024-02-26T17:16:37+05:30",
"payment_method_type":"card",
"ru":"https://www.merchanturl.com/response.jsp",
"card":{
"paymentaccountid":"PA0385154645099",
"masked_value":"xxxxxxxxxxxx2426",
"holder_name":"John",
"type":"CREDIT",
"card_end":"2426",
"network":"MASTER",
"issuer":"Yes Bank",
"cardaccountid":"CA052BE0000058210609"
},
"customer":{
},
"verification_error_code":"TRS0000",
"verification_error_type":"success",
"verification_error_desc":"Transaction Successful",
"issuer_ref_no":"X5nfLK69PY",
"recurrence_rule":"after",
"debit_day":"1",
"is_amex_flow":"N",
"bank_umrn":"X5nfLK69PY"
}

B) For action "delete"

terminal_state=Y&mandate_tokenid=NN054919682783&mandate_response=eyJhbGciOiJIUzI1NiIsImNsaWVudGlkIjoiYmRobWFjdGVzdCIsImtpZCI6IkhNQUMifQ.eyJtYW5kYXRlaWQiOiJNTjExNkExNTcwNDU2OTIiLCJ2ZXJpZmljYXRpb25fZXJyb3JfY29kZSI6Ik1OUzAwMDAiLCJ2ZXJpZmljYXRpb25fZXJyb3JftHlwZSI6InN1Y2Olc3MiLCJjcmVhdGVkb24iOiIyMDI0LTAyLTI2VDE3OjA4OjI2KzA1OjMwIiwidmVyaWZpY2F0aW9uX2Vycm9yX2Rlc2MiOiJNYW5kYXRlIFN1Y2Nlc3NmdWwiLCJzdGF0dXMiOiJERUxFVEVEIn0.Ffm1e-HwKW2-wkG3NIlsvC06lY2M5CCBjMhvGZ1lTv4&keyid=HMAC&objectid=mandate

ru=https%3A%2F%2Fwww.merchant.com&mandateid=MN2592157051326&mandate_tokenid=NN255F19684347&mandate_response=eyJhbGciOiJIUzI1NiIsImNsaWVudGlkIjoiYmRobWFjdGVzdCIsImtpZCI6IkhNQUMifQ.eyJlbmRfZGF0ZSI6IjIwMjYtMDgtMjAiLCJwYXltZW50X21ldGhvZF90eXBlIjoiY2FyZCIsInJ1IjoiaHR0cHM6Ly93d3cubWVyY2hhbnR1cmwuY29tL3Jlc3BvbnNlLmpzcCIsInZlcmlmaWNhdGlvbl9lcnJvcl90eXBlIjoic3VjY2VzcyIsInRyYW5zYWN0aW9uaWQiOiJNVDI1QzkxMjM3OTE0MDAiLCJmcmVxdWVuY3kiOiJ3ZWVrIiwiYW1vdW50X3R5cGUiOiJmaXhlZCIsInZlcmlmaWNhdGlvbl9lcnJvcl9jb2RlIjoiVFJTMDAwMCIsInN1YnNjcmlwdGlvbl9yZWZpZCI6IlN1aGZiZmJmZnJ0IiwiY3VycmVuY3kiOiIzNTYiLCJyZWN1cnJlbmNlX3J1bGUiOiJhZnRlciIsInN0YXJ0X2RhdGUiOiIyMDI0LTAyLTI2IiwibWVyY2lkIjoiVjJCRE1PTjEiLCJhbW91bnQiOiIxMC4wMCIsImRlbGV0ZWRvbiI6IjIwMjQtMDItMjZUMTc6NTQ6MTgrMDU6MzAiLCJzdWJzY3JpcHRpb25fZGVzYyI6IkFWU2RodmZpYmZmeXVlcmZ0aW5laXUiLCJjcmVhdGVkb24iOiIyMDI0LTAyLTI2VDE3OjU0OjE4KzA1OjMwIiwiY3VzdG9tZXJfcmVmaWQiOiJjdXN0ZmVmYmZydCIsIm1hbmRhdGVpZCI6Ik1OMjU5MjE1NzA1MTMyNiIsImRlYml0X2RheSI6IjEiLCJvYmplY3RpZCI6Im1hbmRhdGUiLCJjYXJkIjp7ImNhcmRhY2NvdW50aWQiOiJDQTA1MkJGMDAwMDAzODIxMDY1OSIsImNhcmRfZW5kIjoiMjQyNiIsInBheW1lbnRhY2NvdW50aWQiOiJQQTAzODUxNTQ2MzUwOTkiLCJ0eXBlIjoiQ1JFRElUIiwiaXNzdWVyIjoiWWVzIEJhbmsiLCJtYXNrZWRfdmFsdWUiOiJ4eHh4eHh4eHh4eHgyNDI2IiwiaG9sZGVyX25hbWUiOiJBcmp1biIsIm5ldHdvcmsiOiJNQVNURVIifSwidmVyaWZpY2F0aW9uX2Vycm9yX2Rlc2MiOiJUcmFuc2FjdGlvbiBTdWNjZXNzZnVsIiwic3RhdHVzIjoiZGVsZXRlZCIsImN1c3RvbWVyIjp7fX0.uwYK-NrV3SQaxzjtoTna4zIL0Yz7YDGB-wgFJo6_V1A&return_url=https%3A%2F%2Fwww.merchant.com&keyid=HMAC&objectid=mandate&transactionid=MT25C9123791400

{
"objectid":"mandate",
"mandateid":"MN10A1157059143",
"mercid":"BDMERCID",
"customer_refid":"custfefbffrt",
"subscription_refid":"Suhfbfbfffrt",
"subscription_desc":"AVSdhvfibfffyuerftineiu",
"start_date":"2024-02-26",
"end_date":"2026-08-20",
"amount":"10.00",
"amount_type":"fixed",
"currency":"356",
"frequency":"week",
"status":"deleted",
"createdon":"2024-02-26T18:06:04+05:30",
"deletedon":"2024-02-26T18:27:00+05:30",
"payment_method_type":"upi",
"ru":"https://www.merchanturl.com/response.jsp",
"upi":{
"paymentaccountid":"PA0F95154692897",
"vpa":"john.doe@okaxis",
"psp":"okaxis"
},
"customer":{

},
"verification_error_code":"MNS0000",
"verification_error_type":"success",
"verification_error_desc":"Mandate Successful",
"recurrence_rule":"after",
"debit_day":"1",
"bank_umrn":"d70703b954ec42fb9eb80d75d69ac21d@okaxis"
}

{
"objectid":"mandate",
"mandateid":"MN2592157051326",
"mercid":"BDMERCID",
"customer_refid":"custfefbfrt",
"subscription_refid":"Suhfbfbffrt",
"subscription_desc":"AVSdhvfibffyuerftineiu",
"start_date":"2024-02-26",
"end_date":"2026-08-20",
"amount":"10.00",
"amount_type":"fixed",
"currency":"356",
"frequency":"week",
"status":"deleted",
"createdon":"2024-02-26T17:16:37+05:30",
"deletedon":"2024-02-26T17:54:18+05:30",
"payment_method_type":"card",
"ru":"https://www.merchanturl.com/response.jsp",
"card":{
"paymentaccountid":"PA0385154635099",
"masked_value":"xxxxxxxxxxxx2426",
"holder_name":"John",
"type":"CREDIT",
"card_end":"2426",
"network":"MASTER",
"issuer":"Yes Bank",
"cardaccountid":"CA033BF0000048210659"
},
"customer":{

},
"verification_error_code":"TRS0000",
"verification_error_type":"success",
"verification_error_desc":"Transaction Successful",
"issuer_ref_no":"X5nfLK69PY",
"recurrence_rule":"after",
"debit_day":"1",
"is_amex_flow":"N",
"bank_umrn":"X5nfLK69PY"
}

Alternately, merchant can also use the mandateid parameter and call the Retrieve Mandate API to query the status of the mandate.