Creating physical mandate requests via the Source API endpoint

This guide refers to API endpoints in API Reference (in the Dashboard, go to Developers > API Reference).

The Source endpoint assumes that you already have the full details required to create a physical mandate. If you don't have all of the details, you'll need to build a form to capture the details from the customer. Alternatively, you can use a white-labelled LotusPay hosted form.

You take the customer's ink signature on a printed paper mandate. You take a photo/scan of the paper mandate and send it to LotusPay. You can use the LotusPay pre-filled PDF which is in the standard NPCI format, or you can use your own blank or partially-filled mandate stationery (ensuring that the hand-written data precisely matches the source data).

The physical mandate creation process requires both soft data and scan image. Once you submit both, LotusPay moderates them and submits them to the sponsor bank for processing in the NACH system. Once NPCI acknowledges the mandate request, a mandate is created with a UMRN. Once the destination bank responds with the final status, the mandate transitions to active or failed.

Source has no further use after the mandate is created - all of the relevant details can be retrieved from the mandate.

See Source statuses for more details.

Methods

The physical mandate creation flow can use any of the following methods, depending on your use case. Whichever method you use, you'll need to ensure that the image is of the required standard.

To use the LotusPay pre-filled PDF, create the source first and then fetch the PDF file using GET Source PDF API. You can also download the PDF from the mandate page on the LotusPay dashboard.

a) Checkout method

If the customer is in session in your web app or mobile app, you can create an ecommerce-style instant check-out experience for the customer by giving them a pre-filled mandate template to print and sign. If you want to use the LotusPay pre-filled PDF file, you'll have to create the source first, and then fetch the PDF file. You can then guide the customer to take a photo of the signed paper mandate and upload it to your mobile or web app.

b) Invitation method

If you want LotusPay to send an email invitation to the customer for them to authorise in their own time, create a source first including an email address in the debtor_email argument, and an email will be sent to your customer within a few seconds with the LotusPay pre-filled PDF file attached. The display name of the From email address will be your company's trading name, and your company logo will be displayed.

c) Origination method

If you have your own procedure for originating the signed paper mandate, you can use that.

Source and Image Processing

The flow is as follows:

Step 1. You create source via a server-to-server POST request using the POST Source API with the required arguments. source.status is initially pending. source.mandate and source.redirect.response are initially empty. The source remains usable until source.status is pending_submission or withdrawn. LotusPay informs you of the source creation by asynchronously sending server-to-server event POST requests to your webhook URL of type source.pending (containing the full source payload). Alternatively you can create the source via import, via the dashboard source form, or via public agent forms.

Step 2. You create physical_mandate_image via a server-to-server POST request using the POST Physical Mandate Image API with the required arguments. Alternatively, you can use the LotusPay NACH Android mobile app to take a cropped photo and directly upload it to LotusPay. Alternatively, you can get the photo/scan on your computer desktop and upload it in the dashboard source page (this has a cropping feature) if the source has already been created.

Note: Steps 1 and 2 can be done in reverse order i.e. you can create the physical_mandate_image before the source. As long as reference1 is matching in both objects then the two will be automatically linked.

Step 3. You check that the source data is matching the scan image, and that the scan image is of a suitable quality. See here for more details. You then use the POST Source Process API to send the source for processing. Alternatively, you can click on Process in the source page on the dashboard. This step acts as the checker stage of a 'maker-checker' protocol, if so required. source.status moves to pending_submission.

Step 4. LotusPay checks the source data and scan image on the same working day if received before 4pm and either submits it to the sponsor bank for onward processing or returns it to you for correction.

In the Test environment, each scenario can be simulated from the individual source page in the dashboard.

Submit scenario: If the data and image are matching and the image is of the required quality:

• source.status moves to submitted. LotusPay submits the source to the sponsor bank on the same working day if the source was received an hour before the sponsor bank's cutoff time, else the next working day.

• LotusPay informs you of the submission by asynchronously sending server-to-server event POST request to your webhook URL of type source.submitted (containing the full source payload). If you are not integrating the webhook, you can use the GET Source API to periodically check the status.

Return scenario: If LotusPay finds any error e.g. data mismatch, poor image quality etc. then we return it to pending. This is rare if your image quality and data quality are good:

• source.status returns to pending. source.redirect.response is populated with the LotusPay response, including error in source.redirect.response.

• LotusPay informs you of the error by asynchronously sending a server-to-server event POST request to your webhook URL of type source.pending (containing the full source payload). You can differentiate this from a creation event because the error event contains a value in source.redirect.response. If you are not integrating the webhook, you can use the GET Source API to periodically check the status. We also send an email to your operations email address.

• Manually review the source, and decide whether to withdraw or re-process. If the issue is with the image, you may create a new physical_mandate_image for the same source and again process the source. If the issue is with the data, you should withdraw this source object and create a new one (you can withdraw it via the POST Source Withdraw API endpoint to transition source.status to withdrawn).

Step 5. The sponsor bank checks the mandate request data and scan image and either sends it onward for processing or denies it. This is usually done on the same working day, else the next working day.

In the Test environment, each scenario can be simulated from the individual source page in the dashboard.

 Acknowledged scenario: If the sponsor bank submits the mandate request to NPCI and NPCI acknowledges it by assigning a Unique Mandate Reference Number (UMRN):

• mandate is created including the exact set of attributes as were requested in source.nach_debit arguments. mandate.status is acknowledged. mandate.umrn is populated with the UMRN. mandate.source is populated with the ID of the source that originated it. source.mandate is populated with the ID of the newly created mandate.

• LotusPay informs you of the mandate acknowledgement by asynchronously sending server-to-server event POST request to your webhook URL of type mandate.acknowledged (containing the full mandate payload). If you are not integrating the webhook, you can use the GET Mandate API to periodically check the status.

Not Acknowledged scenario: If the sponsor bank denies the mandate request, or if the sponsor bank submits it to NPCI and NPCI denies to acknowledge it (known as "Ack Reject"), then the source returns to pending submission. Then LotusPay may resubmit it or may return it to pending:

• source.status returns to pending_submission and then possibly to pending. source.redirect.response is populated with the sponsor bank or NPCI response, including error in source.redirect.response. source.mandate remains empty.

• mandate is not created.

• LotusPay informs you of the error by asynchronously sending a server-to-server event POST request to your webhook URL of type source.pending (containing the full source payload). You can differentiate this from a creation event because the error event contains a reason in source.redirect.response. If you are not integrating the webhook, you can use the GET Source API to periodically check the status.

• If the issue is with the image, you may create a new physical_mandate_image for the same source and again process the source. If the issue is with the data, you should withdraw this source object and create a new one (you can withdraw it via the POST Source Withdraw API endpoint to transition source.status to withdrawn).

Step 6. The destination bank checks the mandate within two to 10 days and either accepts it or rejects it.

In the Test environment, each scenario can be simulated from the individual mandate page in the dashboard.

 Accept scenario: If the destination bank accepts the mandate:

• mandate.status is active and mandate.reason_code is populated with the value ac01 and mandate.reason_description is populated with the description ACK Default Accept Reason.

• LotusPay informs you of the success by asynchronously sending server-to-server event POST request to your webhook URL of type mandate.active (containing the full mandate payload). If you are not integrating the webhook, you can use the GET Mandate API to periodically check the status.

Reject scenario: If the destination bank rejects the mandate:

• mandate.status is failed, mandate.reason_code is populated with the rejection reason e.g. M003 and mandate.reason_description is populated with the description e.g. Drawers signature differs. You may want to create a new source and try again.

• LotusPay informs you of the rejection by asynchronously sending server-to-server event POST request to your webhook URL of type mandate.failed (containing the full mandate payload). If you are not integrating the webhook, you can use the GET Mandate API to periodically check the status.

Compliance

RBI, NPCI and sponsor banks have strict rules regarding processing, archiving and retrieval of physical paper mandates. It's your responsibility to abide by these rules.

Next steps

If mandate was successfully created, you may want to create an ach_debit or a subscription.

Source statuses, mandate statuses and webhooks

See the articles linked below on source statuses and mandate statuses for detailed information.

Your integration needs to use our webhooks to be notified of status changes on source, mandate and ACH debit objects.