The Source endpoint assumes that you already have the full details required to create a mandate or that you are using LotusPay.js. 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.
Source has no further use after the mandate is created - all of the details can be retrieved using the Mandate endpoint.
The eMandate redirect flow can use the Checkout method or the Invitation method. See below for further details on each method.
In this graphic, each orange arrow represents an API request, and each linked blue box represents a view.
* ONMAGS = Online Mandate Approval Gateway System.
** Eligible pro merchants can request LotusPay to hide the LotusPay page if they make a compliant page in their web/mobile application.
The flow is as follows:
Step 1. [Checkout method only] The customer starts in your web/mobile application. If you need to capture any details from the customer, you can build a form. If you need to capture just the customer's bank account details, you can use LotusPay.js.
Server-to-server: You create a `source` with fully pre-filled NACH Debit parameters using the POST method. LotusPay returns a `mandate` with an authorisation link in `url`. The link remains usable until the mandate is authorised or withdrawn.
Browser-to-browser: You forward the customer to this URL using the GET method. In a mobile app, you would open this page in a webview (or you can use the LotusPay Mobile SDK to handle this for you).
Step 2. The customer visits the link and reviews the mandate. This page is certified by NPCI and hosted by LotusPay. The customer accepts the terms of the mandate and agrees to proceed.
Step 3. The customer gets redirected to NPCI's Online Mandate Approval Gateway System (ONMAGS). They see a brief interstitial animation and get forwarded again.
Step 4. The customer gets redirected to their bank's website. Here they must complete the mandate authorisation via netbanking login or debit card and PIN (depending on the option chosen earlier). See this article for screenshot, video and more information regarding the customer's experience. This displays a status to the customer and sends them back to NPCI.
Step 5. The customer sees a brief success/error message on ONMAGS and gets redirected back to LotusPay.
Step 6. The customer sees a success/error message on LotusPay.
Server-to-server: LotusPay instantly informs you of the ONMAGS response by synchronously sending an `event` POST request to your webhook url, containing the full GET Mandate payload. This includes the `onmags_response` value and the mandate status. You may also use the GET Mandate API to get the full mandate payload, including its status and the ONMAGS response.
Success scenario: If the customer has successfully authorised the `mandate`, the mandate moves from `pending` status to `submitted` status and the authorisation link becomes blocked from further attempts. This creates an event and a synchronous webhook post.
Error scenario: If the mandate authorisation has returned an error for any reason, or if the customer declined the mandate, and the customer returns to LotusPay, the mandate remains in `pending` status and the `url` remains active so that the customer can retry with the same link. This creates an event and a synchronous webhook post. If ONMAGS gave an error reason and message, it will be shown in `onmags_response`. Checkout method: If you want the customer to retry, you can resend them to the same `url`. If you want to block the customer from retrying with the same `url`, you must use the Mandate Cancel API endpoint to withdraw it. Invitation method: the customer can revisit the link and reattempt authorisation.
Step 7. If you supplied `return_url` in Source, the customer gets redirected to your Return URL. If you opened a webview in a mobile app, at this stage you can close the webview and take back control into your app. You can use the LotusPay Mobile SDK to handle this for you. Returning to your web/mobile app happens regardless of whether mandate authorisation was successful or not.
At this stage, you may want to create an ACH debit/payment or a subscription.
You can create an ecommerce-style instant check-out experience for the customer by redirecting them to the `url` from your web application, or by opening a webview in your mobile application.
In this method, the customer starts in Step 1.
Eligible merchants can build their own custom payment page certified by LotusPay, in which case the customer will not see the LotusPay mandate page (Step 2) - they will go from Step 1 to Step 3. Contact LotusPay Support for more information.
You can send a fully pre-filled eMandate invitation to a customer for them to authorise in their own time.
In this method, the customer starts in Step 2.
When the customer visits this link, they land directly on the LotusPay mandate page.
If you want LotusPay to send the `url` link to your customer via email, you can include an email address in the `email` argument and an email will be instantly sent to your customer. The display name of the From email address will be your company's trading name, and your company logo will be displayed.
If your merchant account is enabled for SMS notifications, and you want LotusPay to send the `url` link to your customer via SMS, you can include their mobile number in the `mobile` argument, and a short link will be instantly sent (in live mode only) to that mobile number. * Requires Pro Plan upgrade *
Otherwise, you can share the `url` link independently via your own method such as email/SMS/chat etc.
If you want to terminate the link at any time, you must use the Mandate Cancel API endpoint to withdraw the mandate.
If you include a `return_url`, LotusPay populates it with the following GET parameters when returning your customer to your website:
* `mandate_id`: A string representing the ID of the `mandate` object.
* `livemode`: Indicates if this is a live mandate, either `true` or `false`.
* `client_secret`: used to confirm that the returning customer is the same one who triggered the creation of the source (source IDs and mandate IDs are not considered secret)
You may include any other GET parameters you may need when specifying `return_url`. Do not use the above as parameter names yourself as these would be overridden with the values we populate.
Mandate statuses and webhooks
See this article on mandate statuses for detailed information.
Your integration needs to use our webhooks to be notified of status changes on mandate, payment and ACH debit objects.
Some customers using NACH Debit assume that the mandate authorisation process is complete once they have completed Step 4. This results in customers who close their browser instead of following the redirect and returning to LotusPay, and thereafter to your app or website. For these reasons it is essential that your integration rely on webhooks to determine when the mandate becomes active. Please refer to our webhooks guide for more details.