NAV Navbar
curl http

TOPICS

Introduction

LotusPay enables businesses to collect recurring payments via NACH Debit eMandates (eNACH). Merchants can use LotusPay via the dashboard or the API.

The LotusPay eNACH API is organised around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors. We have language bindings in Shell (cURL).

Be sure to subscribe to LotusPay's API announcement mailing list to receive information on new additions and changes to LotusPay's API.

Base URLs

To make the API as explorable as possible, live accounts have live mode API keys and test accounts have test mode API keys. The base URLs for the LotusPay API are:

There is no "switch" for changing between modes, just use the appropriate key and URL to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

The sample requests in the right sidebar are designed to work as is. The sample requests are performed using a test mode API key and they have the test URL. When you are moving into production, be sure to use your live key and live URLs. Your live key is available in your live account after your account has been activated. You can sign up for a test account at https://test.lotuspay.com/signup and you can request your test API key by emailing us. Click here for more information about test accounts.

Authentication

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_[keyvalue]" instead of -u sk_test_[keyvalue]:.

All API requests must be made over HTTPS. Calls made over plain HTTP will be auto-forwarded to HTTPS. API requests without authentication will fail.

Errors

{
    "error": {
        "code": "parameter_invalid_integer",
        "doc_url": "https://docs.lotuspay.com/#errors",
        "message": "Invalid positive integer",
        "param": "amount",
        "type": "invalid_request_error"
    }
}

LotusPay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.). Codes in the 5xx range indicate an error with LotusPay's servers (these are rare).

HTTPS status code summary

Code Meaning
200 OK -- Everything worked as expected.
400 Bad Request -- The request was unacceptable, often due to missing a required parameter.
401 Unauthorized -- No valid API key provided.
402 Request Failed -- The parameters were valid but the request failed.
404 Not Found -- The requested resource doesn't exist.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- Too many requests hit the API too quickly.
500 Internal Server Error -- Something went wrong on LotusPay's end. (These are rare.) Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Try again later.

Some 4xx errors that could be handled programmatically (e.g., a parameter is declined) include an error code that briefly explains the error reported.

Our API libraries raise exceptions for many reasons, such as invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Attribute Description
type string The type of error returned. One of api_connection_error, api_error, authentication_error, invalid_request_error, rate_limit_error or validation_error.
code optional string For some errors that could be handled programmatically, a short string indicating the error code reported.
doc_url optional string A URL to more information about the error code reported.
param optional string If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.

Error types

Type Meaning
api_connection_error Failure to connect to LotusPay's API.
api_error API errors cover any other type of problem (e.g., a temporary problem with LotusPay's servers), and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.
validation_error Errors triggered by our system when failing to validate fields (e.g., when an account number or expiration date is invalid or incomplete).

Error codes

account_number_invalid The bank account number provided is invalid (e.g., missing digits). Bank account information varies from bank to bank. We recommend creating validations in your entry forms based on the bank account formats we provide.

amount_too_large The specified amount is greater than the maximum amount allowed. Use a lower amount and try again.

amount_too_small The specified amount is less than the minimum amount allowed. Use a higher amount and try again.

email_invalid The email address is invalid (e.g., not properly formatted). Check that the email address is properly formatted and only includes allowed characters.

invalid_charge_amount The specified amount is invalid. The charge amount must be a positive integer in paisa (one hundredths of a Rupee), and not exceed the minimum or maximum amount.

invalid_mandate_usage The mandate cannot be used because it is not in the correct state (e.g., a charge request is trying to use a mandate with a failed or cancelled mandate). Check the status of the mandate you are attempting to use.

livemode_mismatch Test and live mode API keys, requests, and objects are only available within the mode they are in.

missing Both a customer and mandate ID have been provided, but the mandate does not belong to the customer. To create a charge for a customer with a specified mandate, you must provide the valid customer or provide none.

parameter_invalid_empty One or more required values were not provided. Make sure requests include all required parameters.

parameter_invalid_integer One or more of the parameters requires an integer, but the values provided were a different type. Make sure that only supported values are provided for each attribute. Refer to our API documentation to look up the type of data each attribute supports.

parameter_invalid_string_blank One or more values provided only included whitespace. Check the values in your request and update any that contain only whitespace.

parameter_invalid_string_empty One or more required string values is empty. Make sure that string values contain at least one character.

parameter_missing One or more required values are missing. Check our API documentation to see which values are required to create or modify the specified resource.

parameter_unknown The request contains one or more unexpected parameters. Remove these and try again.

processing_error An error occurred while processing the charge. Check the mandate details are correct or use a different mandate.

resource_missing The ID provided is not valid. Either the resource does not exist, or an ID for a different resource has been provided.

routing_number_invalid The bank IFSC number provided is invalid.

secret_key_required The API key provided is a publishable key, but a secret key is required. Obtain your current API keys from the Dashboard and update your integration to use them.

url_invalid The URL provided is invalid.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions.

The current version is 2018-07-07.

All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.

To set the API version on a specific request, send a LotusPay-Version header.

You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.

Upgrades

Your API version controls the API and webhook behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). Your version gets set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Backwards-compatible changes

LotusPay considers the following changes to be backwards-compatible:

CORE RESOURCES

Bank Accounts

bank_account objects hold the account details of a customer's bank account. bank_account objects are linked to customer, mandate and payment objects. The API allows you to retrieve your bank accounts. You can retrieve individual bank accounts as well as a list of all bank accounts.

The bank account object

Example Response

{
  "id": "BA004433221AA",
  "object": "bank_account",
  "created": 1530224170,
  "account_holder_name": "Amit Jain",
  "account_type": "savings",
  "bank_name": "TEST BANK",
  "customer": "CU004433221AA",
  "ifsc": "TEST0999999",
  "last4": "1234",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [

    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "status": "enabled"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "bank_account" String representing the object's type. Objects of the same type share the same value.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
account_holder_name string Name of the person or business that owns the bank account.
account_type string Type of account. This is savings, current, nre, nro, or cc.
bank_name string Name of the bank associated with the IFSC (e.g. TEST BANK).
customer string Identifier of the customer who owns the bank account.
ifsc string Branch IFSC code.
last4 string Last four digits of the bank account number.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
mandates list List of mandates that are attached to this bank account.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
status string Status of the bank account. Possible values are enabled, disabled. Bank accounts are always enabled unless a user has specifically disabled it. Disabling a bank account cancels its linked mandates and payments. A disabled bank account can be enabled by creating a new bank account with the same account details.

Retrieve a bank account

GET https://api-test.lotuspay.com/v1/customers/{CUSTOMER_ID}/bank_accounts

Example Request

$ curl https://api-test.lotuspay.com/v1/customers/CU004433221AA/bank_accounts/BA004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "BA004433221AA",
  "object": "bank_account",
  "created": 1530224170,
  "account_holder_name": "Amit Jain",
  "account_type": "savings",
  "bank_name": "TEST BANK",
  "customer": "CU004433221AA",
  "ifsc": "TEST0999999",
  "last4": "1234",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [

    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "status": "enabled"
}

By default, you can see the 10 most recent bank accounts stored on a customer directly on the object, but you can also retrieve details about a specific bank account stored on the LotusPay account.

Retrieves an existing bank account object. Supply the unique bank account identifer.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the bank account to be retrieved.
customer REQUIRED The identifier of the customer who owns the bank account.

Returns Returns a bank account object if a valid identifier was provided.

List all bank accounts

GET https://api-test.lotuspay.com/v1/customers/{CUSTOMER_ID}/bank_accounts

Example Request

$ curl https://api-test.lotuspay.com/v1/customers/CU004433221AA/bank_accounts?limit=2 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G

Example Response

{
  "object": "list",
  "url": "/v1/customers/CU004433221AA/bank_accounts",
  "has_more": false,
  "data": [
        {
            "id": "BA004433221AA"
        },
        {
            "id": "BA004433221BB"
        }
  ]
}

You can see a list of the bank accounts belonging to a customer. The bank accounts are returned sorted by creation date, with the most recent appearing first. Note that the 10 most recent bank accounts are always available by default on the customer. If you need more than those 10, you can use this API method and the limit parameter to page through bank accounts.

ARGUMENTS

Argument Description
customer REQUIRED The identifier of the customer whose bank accounts will be retrieved.
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns A dictionary with a data property that contains an array of up to limit bank accounts. Each entry in the array is a separate bank account object. If no more bank accounts are available, the resulting array will be empty.

Customers

customer objects hold the contact details for a customer. They allow you to track multiple bank_account, mandate, subscription and payment objects that are associated with the same customer. The API allows you to retrieve your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object

Example Response

{
  "id": "CU004433221AA",
  "object": "customer",
  "bank_accounts": {
    "object": "list",
    "data": [
    {
        "id": "BA0011223344BB"
    },
    ],
    "total_count": 1,
    "url": "/v1/customers/CU004433221AA/bank_accounts"
  },
  "created": 1530224170,
  "description": null,
  "email": "amit@gmail.com",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
        {
            "id": "MD0011223366A"
        },
        {
            "id": "MD00123459DDA"
        }
    ],
    "total_count": 2,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "pan": "ABCDE1234A",
  "phone": "9123456789",
  "subscriptions": {
    "object": "list",
    "data": [
        {
            "id": "SB0011223322D"
        }
    ],
    "total_count": 1,
    "url": "/v1/customers/CU004433221AA/subscriptions"
  }
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "customer" String representing the object's type. Objects of the same type share the same value.
bank_accounts list The customer's bank accounts, if any. See child attributes below.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
description string An arbitrary string attached to the object. Often useful for displaying to users.
email string Customer’s email address.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
mandates list The customer's NACH Debit mandates, if any. See child attributes below.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mobile string Customer's mobile number (including country code).
name string Customer's name.
pan string The customer's Permanent Account Number (tax ID in India).
phone string Customer's phone.
subscriptions list The customer's subscriptions, if any. See child attributes below.

Child attributes for lists of linked bank_accounts, mandates and subscriptions:

Attribute Description
object string, value is list String representing the object’s type. Objects of the same type share the same value. Always has the value list.
data array The list contains all related objects that have been attached to the customer.
total_count integer The total number of items in the array.
url string The URL where this list can be accessed.

Retrieve a customer

GET https://api-test.lotuspay.com/v1/customers

Example Request

$ curl https://api-test.lotuspay.com/v1/customers/CU004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "CU004433221AA",
  "object": "customer",
  "bank_accounts": {
    "object": "list",
    "data": [
    {
        "id": "BA0011223344BB"
    },
    ],
    "total_count": 1,
    "url": "/v1/customers/CU004433221AA/bank_accounts"
  },
  "created": 1530224170,
  "description": null,
  "email": "amit@gmail.com",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
        {
            "id": "MD0011223366A"
        },
        {
            "id": "MD00123459DDA"
        }
    ],
    "total_count": 2,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "pan": "ABCDE1234A",
  "phone": "9123456789",
  "subscriptions": {
    "object": "list",
    "data": [
        {
            "id": "SB0011223322D"
        }
    ],
    "total_count": 1,
    "url": "/v1/customers/CU004433221AA/subscriptions"
  }
}

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the customer to be retrieved.

Returns Returns a customer object if a valid identifier was provided.

List all customers

GET https://api-test.lotuspay.com/v1/customers

Example Request

$ curl https://api-test.lotuspay.com/v1/customers?limit=6 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G

Example Response

{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
        {
            "id": "CU004433221AA"
        },
        {
            "id": "CU004433221BB"
        },
        {
            "id": "CU004433221CC"
        },
        {
            "id": "CU004433221DD"
        },
        {...
        }
  ]
}

You can see a list of your customers. The customers are returned sorted by creation date, with the most recent appearing first. You can use this API method and the limit parameter to page through customers.

ARGUMENTS

Argument Description
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns A dictionary with a data property that contains an array of up to limit customers. Passing an optional email will result in filtering to customers with only that exact email address. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never return an error.

Mandates

mandate objects represent the NACH Debit mandates with customers. Mandates are attached to customer, bank_account and subscription objects. payment objects are linked to mandate objects. The API allows you to retrieve your mandates. You can retrieve individual mandates as well as a list of all mandates.

The mandate object

Example Response

{
  "id": "MD004433221AA",
  "object": "nach_debit_mandate",
  "account_holder_name": "Amit Jain",
  "account_last4": "1234",
  "account_type": "savings",
  "amend_status": null,
  "bank_account": "BA004433DD55AA",
  "cancel_status": null,
  "cancel_reason": null,
  "category_code": "S004",
  "collection_amount": 1000,
  "created": 1530224170,
  "creditor": "LOTUSPAY SOLUTIONS PVT LTD",
  "creditor_agent": "TEST BANK",
  "creditor_agent_mmbid": "TEST0111111",
  "customer": "CU00443311DDAA",
  "customer_email": "amit@example.com",
  "customer_mobile": "9999123456",
  "customer_name": "Amit Jain",
  "customer_pan": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "debtor_agent": "OTHER BANK",
  "debtor_agent_mmbid": "OTHE0111111",
  "esign_mode": "otp",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "TEST BANK",
  "instructing_agent_mmbid": "TEST0111111",
  "instructed_agent": "OTHER BANK",
  "instructed_agent_mmbid": "OTHE0111111",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MERCHANTREF2",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "esign"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "nach_debit_mandate" String representing the object’s type. Objects of the same type share the same value.
account_holder_name string Name of the person or business that owns the bank account.
account_last4 string Last four digits of the customer's bank account number.
account_type string Type of account. One of savings, current, nre, nro or cc.
amend_status string The amend status of the mandate, one of amend_requested, amend_submitted, amend_confirmed, amend_failed, or amend_received. For details see support article on mandate statuses.
bank_account string Identifier of the customer bank account of the mandate.
cancel_status string The cancel status of the mandate, one of cancel_requested, cancel_submitted, cancel_confirmed, cancel_failed, or cancel_received. For details see support article on mandate statuses.
cancel_reason string The cancellation reason. Either C001 or C002.
category_code string The industry classification code of the mandate. See Support article on mandate category codes.
collection_amount integer Collection amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Only one of collection_amount or maximum_amount will be present, never both.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
creditor string The creditor of the mandate.
creditor_agent string Name of the bank associated with the below IFSC (e.g. TEST BANK) - also known as the sponsor bank.
creditor_agent_mmbid string The NACH IFSC code of the creditor's sponsor bank.
customer string Identifier of the customer.
customer_email string Email address of the customer.
customer_mobile string Mobile number of the customer.
customer_name string Name of the customer in the linked customer object. Does not appear in the actual mandate.
customer_pan string PAN number of the customer.
customer_phone string Phone number of the customer.
date_acknowledged date Date on which the mandate was acknowledged by NPCI - the UMRN was generated.
date_amended date Date on which the mandate was amended.
date_cancelled date Date on which the mandate was cancelled.
date_responded date Date on which the destination bank responded.
debtor_agent string Name of the bank associated with the below IFSC (e.g. OTHER BANK) - also known as the destination bank.
debtor_agent_mmbid string The branch IFSC code of the customer's bank account.
esign_mode string The Aadhaar eSign authentication mode of the mandate when variant is esign. Either otp or biometric.
failure_reason string The failure reason for the redirect, either user_abort (the customer aborted or dropped out of the redirect flow), declined (the authentication failed or the transaction was declined), or processing_error (the redirect failed due to a technical error). Present only if the redirect status is failed.
first_collection_date date The first collection date (start date) of the mandate.
final_collection_date date The final collection date (end date) of the mandate.
frequency string The frequency with which debit transaction instructions will be created and processed. Value can be ADHO, INDA,DAIL, WEEK, MNTH, BIMN, QURT, MIAN, YEAR. See mandate frequencies support article for more information.
instructing_agent_mmbid string The instructing agent bank of the mandate. This is usually equal to the creditor_agent_mmbid if variant is esign and is always debtor_agent_mmbid if variant is npci_api.
instructing_agent string The bank name of the instructing agent.
instructed_agent_mmbid string The instructed agent of the mandate. This is usually equal to the debtor_agent_mmbid if variant is esign and is always creditor_agent_mmbid if variant is npci_api.
instructed_agent string The bank name of the instructed agent.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
maximum_amount integer Maximum amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Only one of collection_amount or maximum_amount will be present, never both.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
nach_utility_code string NACH utility code of the creditor.
occurrence_sequence_type string The occurrence sequence type of the mandate. Either RCUR or OOFF.
reference1 string Merchant's own customer identifier.
reference2 string LotusPay mandate identifier.
return_url string The URL you provided to redirect the customer to after they authenticated their payment.
show_lotuspay boolean Boolean indicating whether customer will be shown the LotusPay authorisation page during the redirect flow. Value is generally true unless merchant has built custom payment pages approved by LotusPay.
status string The status of the mandate, one of pending, pending_submission, submitted, acknowledged, active, failed, cancelled, expired or withdrawn. For details see support article on mandate statuses.
subscription string Identifier of the subscription linked to the mandate.
umrn string The NACH unique mandate reference number of the mandate.
url string The URL provided to you to redirect a customer to as part of a redirect authentication flow.
variant string The variant of the mandate. Either esign or npci_api.

Retrieve a mandate

GET https://api-test.lotuspay.com/v1/mandates

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/MD004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "MD004433221AA",
  "object": "nach_debit_mandate",
  "account_holder_name": "Amit Jain",
  "account_last4": "1234",
  "account_type": "savings",
  "amend_status": null,
  "bank_account": "BA004433DD55AA",
  "cancel_status": null,
  "cancel_reason": null,
  "category_code": "S004",
  "collection_amount": 1000,
  "created": 1530224170,
  "creditor": "LOTUSPAY SOLUTIONS PVT LTD",
  "creditor_agent": "TEST BANK",
  "creditor_agent_mmbid": "TEST0111111",
  "customer": "CU00443311DDAA",
  "customer_email": "amit@example.com",
  "customer_mobile": "9999123456",
  "customer_name": "Amit Jain",
  "customer_pan": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "debtor_agent": "OTHER BANK",
  "debtor_agent_mmbid": "OTHE0111111",
  "esign_mode": "otp",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "TEST BANK",
  "instructing_agent_mmbid": "TEST0111111",
  "instructed_agent": "OTHER BANK",
  "instructed_agent_mmbid": "OTHE0111111",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MERCHANTREF2",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "esign"
}

Retrieves an existing mandate object. Supply the unique mandate identifer.

ARGUMENTS

Argument Description
id optional The identifier of the mandate to be retrieved. Either id or umrn must be supplied.
umrn optional The NACH unique mandate reference number of the mandate to be retrieved. This attribute will not be present until the mandate has reached acknowledged status. Either id or umrn must be supplied.

Returns Returns a mandate object if a valid identifier was provided.

Cancel a mandate

DELETE https://api-test.lotuspay.com/v1/mandates

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/MD004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X DELETE \
   -d cancel_reason="C001"
DELETE https://api-test.lotuspay.com/v1/mandates/MD004433221AA

{
  "cancel_reason": "C001"
}

Example Response

{
  "id": "MD004433221AA",
  "object": "nach_debit_mandate",
  "account_holder_name": "Amit Jain",
  "account_last4": "1234",
  "account_type": "savings",
  "amend_status": null,
  "bank_account": "BA004433DD55AA",
  "cancel_status": "cancel_submitted",
  "cancel_reason": "C001",
  "category_code": "S004",
  "collection_amount": 1000,
  "created": 1530224170,
  "creditor": "LOTUSPAY SOLUTIONS PVT LTD",
  "creditor_agent": "TEST BANK",
  "creditor_agent_mmbid": "TEST0111111",
  "customer": "CU00443311DDAA",
  "customer_email": "amit@example.com",
  "customer_mobile": "9999123456",
  "customer_name": "Amit Jain",
  "customer_pan": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "debtor_agent": "OTHER BANK",
  "debtor_agent_mmbid": "OTHE0111111",
  "esign_mode": "otp",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "TEST BANK",
  "instructing_agent_mmbid": "TEST0111111",
  "instructed_agent": "OTHER BANK",
  "instructed_agent_mmbid": "OTHE0111111",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MERCHANTREF2",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "esign"
}

Cancels an existing mandate object. Supply the unique mandate identifer or the UMRN. The mandate must be in a cancellable status i.e. pending, pending_submission, submitted, acknowledged or active (if status is active then cancel_status should be null).

ARGUMENTS

Argument Description
id optional The identifier of the mandate to be cancelled. Either id or umrn must be supplied.
umrn optional The NACH Unique Mandate Reference Number of the mandate to be cancelled. This attribute will not be present until the mandate has reached acknowledged status. Either id or umrn must be supplied.
cancel_reason optional, default is C002 The cancellation reason. Either C001 (cancellation on customer request) or C002 (cancellation on merchant request).

Returns Returns a withdrawn/cancelled mandate object if a valid identifier was provided. If the status was pending or pending_submission, the status will change to withdrawn. If the status was submitted, acknowledged or active, the cancel_status will change to cancellation_requested. See support article for more information on mandate cancellation flows.

List all mandates

GET https://api-test.lotuspay.com/v1/mandates

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates?limit=10 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G

Example Response

{
  "object": "list",
  "url": "/v1/mandates",
  "has_more": false,
  "data": [
    {
        "id": "MD004433221AA"
    },
    {
        "id": "MD004433221BB"
    },
    {
        "id": "MD004433221CC"
    },
    {
        "id": "MD004433221DD"
    },
    {...
    }
  ]
}

You can see a list of your mandates. The mandates are returned sorted by creation date, with the most recent appearing first. You can use this API method and the limit parameter to page through mandates.

ARGUMENTS

Argument Description
bank_account optional Only return mandates for the bank_account specified by this identifier. If you pass this argument, you cannot also pass customer or payment.
customer optional Only return mandates for the customer specified by this identifier. If you pass this argument, you cannot also pass bank_account or payment.
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
payment optional Only return mandates for the payment specified by this identifier. If you pass this argument, you cannot also pass bank_account or customer.

Returns A dictionary with a data property that contains an array of up to limit mandates. Passing an optional customer, bank_account, or payment will result in filtering to mandates with only that exact object. Each entry in the array is a separate mandate object. If no more mandates are available, the resulting array will be empty.

Payments

payment objects represent payments taken from a customer to a creditor, taken against an NACH Debit mandate. payment objects are attached to customer, mandate and settlement objects and can also be attached to subscription objects. The API allows you to retrieve your payments. You can retrieve individual payments as well as a list of all of a customer's payments.

The payment object

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 1000,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "description": null,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "settlement": "SM00GGDD22XX",
  "status": "collected",
  "subscription": null,
  "umrn": "TEST000012345678"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "payment" String representing the object’s type. Objects of the same type share the same value.
amount positive integer A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
charge_date date in yyyy-mm-dd format The date on which the payment was or will be scheduled for collection.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
customer string Identifier of the customer this payment was taken from.
description extended length string An arbitrary string attached to the object. Often useful for displaying to users.
failure_code string Error code explaining reason for payment failure if available (see the errors section for a list of codes).
failure_message string Message to user further explaining reason for payment failure if available.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mandate string The identifier of the mandate this payment was or will be taken against.
settlement string The identifier of the settlement which contains the frunds from this payment. Note: This attribute will not be present until the payment has been successfully collected.
status string The status of the payment, one of pending_customer_approval, customer_approval_denied, pending_submission, submitted, cancelled, confirmed, settled, failed or charged_back. For details see support article on mandate statuses.
subscription string The identifier of the subscription from which this payment was created. Note: this property will only be present if this payment is part of a subscription.
umrn string The NACH unique mandate reference number of the mandate.

Create a payment

POST https://api.lotuspay.com/v1/payments

Example Request

$ curl https://api.lotuspay.com/v1/payments \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d amount=2000 \
   -d mandate="MD0011DD22RR33"

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 1000,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "description": null,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "settlement": "SM00GGDD22XX",
  "status": "collected",
  "subscription": null,
  "umrn": "TEST000012345678"
}

Creates a new payment object.

This fails with a invalid_mandate_usage error if the specified mandate is in a non-chargeable state i.e. cancelled, failed, expired or withdrawn.

Payments can be created against mandates with status of: pending_customer_approval, pending_submission, submitted, acknowledged and active. Although you can create payments on mandates that are already linked to subscriptions, it is not advisable. You will have to independently compute whether the mandate has capacity to support additional payments. For example: Suppose a mandate is of frequency monthly and it has a linked subscription recurring monthly - whilst our system will let you create additional payments on this mandate, the customer's bank may reject the second payment in a one month period.

ARGUMENTS

Argument Description
amount REQUIRED Amount in paisa (one hundredths of a Rupee).
charge_date optional, default is the earliest date possible The date (today or a future date) on which the payment should be collected. If not specified, the payment will be collected as soon as possible. This must be on or after the mandate’s first_collection_date and on or before the mandate's final_collection_date. charge_date will be rolled forward by LotusPay to the next working day if it is not a working day. If created before 9am on a working day and passed with no charge_date or charge_date today, the payment will be collected on the same day, else it will be rolled forward by LotusPay.
description optional A human-readable description of the payment. This will be included in the notification email LotusPay sends to your customer.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mandate optional The identifier of the mandate against which this payment should be collected. Either id or umrn must be supplied (one or the other, not both).
umrn optional The NACH Unique Mandate Reference Number of the mandate against which this payment should be collected. Either id or umrn must be supplied (one or the other, not both).

Returns Returns a newly created payment object.

Retrieve a payment

GET https://api-test.lotuspay.com/v1/payments

Example Request

$ curl https://api-test.lotuspay.com/v1/payments/PM004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 20025,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "description": null,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "settlement": "SM00GGDD22XX",
  "status": "settled",
  "subscription": "SB0011DDKKGGEE",
  "umrn": "TEST000012345678"
}

Retrieves an existing payment object. Supply the unique payment identifer.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the payment to be retrieved.

Returns Returns a payment object if a valid identifier was provided.

Cancel a payment

DELETE https://api-test.lotuspay.com/v1/payments

Example Request

$ curl https://api-test.lotuspay.com/v1/payments/PM004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X DELETE

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 20025,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "description": null,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "settlement": "SM00GGDD22XX",
  "status": "cancelled",
  "subscription": "SB0011DDKKGGEE",
  "umrn": "TEST000012345678"
}

Cancels an existing payment object. Supply the unique payment identifer. The payment must be in a cancellable status, i.e. pending_customer_approval or pending_submission.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the payment to be cancelled.

Returns Returns a cancelled payment object if a valid identifier was provided.

List all payments

GET https://api-test.lotuspay.com/v1/payments

Example Request

$ curl https://api-test.lotuspay.com/v1/payments?limit=8 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G 

Example Response

{
  "object": "list",
  "url": "/v1/payments",
  "has_more": false,
  "data": [
        {
            "id": "PA004433221AA"
        },
        {
            "id": "PA004433221BB"
        },
        {
            "id": "PA004433221CC"
        },
        {...
        }
  ]
}

You can see a list of your payments. The payments are returned sorted by creation date, with the most recent appearing first. You can use this API method and the limit parameter to page through payments.

ARGUMENTS

Argument Description
bank_account optional Only return payments for the bank_account specified by this identifier. If you pass this argument, you cannot also pass customer, mandate, subscription or umrn.
customer optional Only return payments for the customer specified by this identifier. If you pass this argument, you cannot also pass bank_account, mandate, subscription or umrn.
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
mandate optional Only return payments for the mandate specified by this identifier. If you pass this argument, you cannot also pass bank_account, customer, subscription or umrn.
subscription optional Only return payments for the subscription specified by this identifier. If you pass this argument, you cannot also pass bank_account, customer, mandate or umrn.
umrn optional Only return payments for the umrn specified by this identifier. If you pass this argument, you cannot also pass bank_account, customer, mandate or subscription.

Returns A dictionary with a data property that contains an array of up to limit payments. Passing an optional bank_account, customer, mandate or subscription will result in filtering to payments with only that exact object. Each entry in the array is a separate payments object. If no more payments are available, the resulting array will be empty. If you provide a non-existent related object identifier, this call returns an error.

Settlements

settlement objects represent transfers from LotusPay to a creditor. Each settlement contains the funds collected from one or many payment objects. Settlements are created automatically after a payment has been successfully collected. The API allows you to retrieve your settlements. You can retrieve individual settlements as well as a list of all settlements.

The settlement object

Example Response

{
  "id": "SM0011DD2211AA",
  "object": "settlement",
  "amount": 2212300,
  "arrival_date": "2018-03-24",
  "created": 1530224170,
  "destination": "BA00CC33221AA",
  "livemode": false,
  "metadata": {
  },
  "method": "instant",
  "status": "settled"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "settlement" String representing the object's type. Objects of the same type share the same value.
amount integer Amount to be transferred to your creditor bank account. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
arrival_date date Date the payout is expected to arrive in the bank. This factors in delays like weekends or bank holidays.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
destination string The identifier of the creditor_bank_account the settlement was sent to.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
method string The method used to send this payout, which can be standard or instant. instant refers to settlements that are paid using internal funds transfer (from and to the same bank) or IMPS. standard refers to settlements that are paid using NEFT and RTGS.
status string Current status of the settlement (pending, settled, processing). A settlement will be pending until it is submitted to the bank, at which point it becomes processing. It will then change to settled when the transaction is confirmed.

Retrieve a settlement

GET https://api-test.lotuspay.com/v1/settlements

Example Request

$ curl https://api-test.lotuspay.com/v1/settlements/SM0011DD2211AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "SM0011DD2211AA",
  "object": "settlement",
  "amount": 2212300,
  "arrival_date": "2018-03-24",
  "created": 1530224170,
  "destination": "BA00CC33221AA",
  "livemode": false,
  "metadata": {
  },
  "method": "instant",
  "status": "settled"
}

Retrieves an existing settlement object. Supply the unique settlement identifer.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the settlement to be retrieved.

Returns Returns a settlement object if a valid identifier was provided.

List all settlements

GET https://api.lotuspay.com/v1/settlements

Example Request

$ curl https://api-test.lotuspay.com/v1/settlements?limit=5 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G

Example Response

{
  "object": "list",
  "url": "/v1/settlements",
  "has_more": false,
  "data": [
        {
            "id": "SM004433221AA"
        },
        {
            "id": "SM004433221BB"
        },
        {
            "id": "SM004433221CC"
        },
        {...
        }
  ]
}

You can see a list of your settlements. The settlements are returned sorted by creation date, with the most recent appearing first. You can use this API method and the limit parameter to page through settlements.

ARGUMENTS

Argument Description
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
status optional Only return settlements that have the given status: pending, processing, or settled.

Returns A dictionary with a data property that contains an array of up to limit settlements. Passing an optional status will result in filtering to settlements with only that exact status. Each entry in the array is a separate settlement object. If no more settlements are available, the resulting array will be empty. If you provide a non-existent related object identifier, this call returns an error.

Sources

source objects represent your request to make pending NACH Debit CREATE mandates i.e. mandate objects. Each source makes either an independent mandate (mandate without a subscription) or a subscription mandate (mandate with a subscription). If existing customer or bank_account objects are passed, source uses them, else source automatically creates new ones.

Sources have no further use after the mandate is created - all of the details can be retrieved using the mandate endpoint.

The overall flow is:

  1. You create a source with pre-filled mandate data and LotusPay returns a mandate with an authorisation url e.g. https://app.lotuspay.com/pay/AL00652J9UYX33, along with a customer, bank_account and possibly a subscription.
  2. Your customer visits the link, enters a password (mobile number or bank account number) and goes through the authorisation process. This displays a status to the customer and redirects them back to the return_url that you supplied. This happens regardless of whether authorisation was successful or not.
  3. LotusPay informs you that the customer has authorised the mandate. If you created an independent mandate, you may wish to create a payment at this point. If you created a subscription mandate, the subscription will automatically create scheduled payments on the mandate.

The source object

Example Response

{
  "id": "SC004433221AA",
  "object": "source",
  "created": 1530224170,
  "customer_details": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "bank_account_details": {
        "account_holder_name": "A JAIN",
        "account_type": "savings",
        "ifsc": "ICIC0000047",
        "last4": "5678"
    },
    "category_code": null,
    "esign_mode": null,
    "mandate_details": {
        "collection_amount": 10000,
        "first_collection_date": "2018-06-18",
        "final_collection_date": null,
        "frequency": "MNTH",
        "maximum_amount": null,
        "occurrence_sequence_type": null
    }
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "show_lotuspay": null,
    "variant": null
  },
  "redirect": {
    "return_url": "https://www.merchant.com/thanks",
    "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D"
  }
  "subscription_details": {
    "amount": null,
    "count": null,
    "day_of_month": null,
    "interval": null,
    "interval_count": null,
    "month": null,
    "name": null,
    "start_date": null
  }
  "type": "nach_debit",
  "bank_account": "BA0011AABBCC22",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
  "subscription": null
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "source" String representing the object's type. Objects of the same type share the same value.
customer_details hash Information about the owner of the payment instrument. See child attributes in table below.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
flow string The authentication flow of the source to create. flow is always redirect for nach_debit.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
nach_debit hash Information for the mandate to be created by the source object. See child attributes in the table below.
redirect hash Information related to the redirect flow. See child attributes in table below.
subscription_details hash Information about the subscription to be created by the source. If subscription_details details are present, mandate_details will be empty, and vice versa.
type string The type of source. The type is a payment method, and is always nach_debit. An additional hash is included on the source with a name matching this value. It contains additional information specific to the payment method used.
bank_account string Identifier of the customer bank account.
customer string Identifier of the customer.
mandate string Identifier of the mandate.
subscription string Identifer of the subscription.

Child attributes for customer_details:

Attribute Description
email string Customer's email address.
mobile string Customer's mobile number.
name string Customer's name.
pan string Customer's Permanent Account Number (tax ID in India).
phone string Customer's phone number.

Child attributes for nach_debit:

Attribute Description
bank_account_details dictionary Information about the bank account on which to create the mandate. See child attributes below.
category_code string Four-digit NPCI code of the mandate category e.g. U099. See support article on mandate category codes for more information.
creditor_name string Name of the creditor of the mandate. The name of the merchant will be displayed on the payment page.
esign_mode string The Aadhaar eSign authentication mode to be used for the nach_debit mandate when variant is esign. Either otp or biometric.
mandate_details dictionary Information about the mandate. See child attributes in table below. If mandate_details details are present, subscription_details will be empty, and vice versa.
nach_sponsor_bank string The 4-digit code of the NACH sponsor bank e.g. HDFC.
nach_utility_code string The NACH utility code of the creditor of the mandate.
reference1 string Merchant's own customer identifier.
reference2 string LotusPay mandate identifier.
show_lotuspay boolean Boolean indicating whether customer will be shown the LotusPay password page and authorisation page during the redirect flow. Value is generally true unless merchant has built custom payment pages approved by LotusPay.
variant string The variant of the mandate to be created, either automatic, esign or npci_api. automatic means LotusPay will automatically assign the variant depending on the bank given or selected, with priority given to npci_api if the destination bank is live for that variant.

Child attributes for bank_account_details:

Attribute Description
account_holder_name string Name of the person or business that owns the bank account.
account_type string Type of account. This is savings, current, nre, nro, or cc.
bank_name string Name of the bank associated with the IFSC (e.g. TEST BANK).
ifsc string Branch IFSC code.
last4 string Last four digits of the bank account number.

Child attributes for mandate_details:

Attribute Description
collection_amount integer Fixed amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Only one of collection_amount or maximum_amount will be present, never both.
first_collection_date date First collection date (start date) of the mandate.
final_collection_date date Final collection date (expiry date) of the mandate. Null entry means "Until Cancelled".
frequency string The frequency with which debit transaction instructions will be created and processed. Value can be ADHO, INDA,DAIL, WEEK, MNTH, BIMN, QURT, MIAN, YEAR. See mandate frequencies table for more information.
maximum_amount integer Maximum amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Only one of collection_amount or maximum_amount will be present, never both.
occurrence_sequence_type string Identifies the underlying transaction sequence as either recurring or one-off. Values can be "RCUR" or "OOFF".

Child attributes for redirect:

Attribute Description
return_url string The URL you provided to redirect the customer to after they authenticated their payment.
url string The URL provided to you to redirect a customer to as part of a redirect authentication flow.

Child attributes for subscription (see the "Create a subscription" endpoint for detailed information): Note: If subscription_details details are present, mandate_details will be empty, and vice versa.

Attribute Description
amount positive integer The fixed amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
count positive integer The total number of payments that should be taken by this subscription. If not specified, the subscription will continue until cancelled.
day_of_month integer As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.
interval string The unit of time between charge dates. One of day, week, month or year.
interval_count positive integer The number of intervals (specified in the interval property) between charge dates. For example, interval=month and interval_count=3 bills every three months.
month string The name of the month on which to charge a customer.
name string The name of the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
start_date date The date on which the first payment will be charged.

Mandate frequencies:

Value Description
ADHO Ad hoc (As and when presented)
INDA Intraday
DAIL Daily
WEEK Weekly
MNTH Monthly
BIMN Bi-monthly
QURT Quarterly
MIAN Half-yearly
YEAR Yearly

Create a source

POST https://api-test.lotuspay.com/v1/sources

Example Request 1

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[bank_account_details[account_holder_name]]="A JAIN" \
    -d nach_debit[bank_account_details[account_number]]="12345678" \
    -d nach_debit[bank_account_details[account_type]]="savings" \
    -d nach_debit[bank_account_details[ifsc]]="ICIC0000047" \
    -d nach_debit[mandate_details[collection_amount]]=10000 \
    -d nach_debit[mandate_details[first_collection_date]]="2018-06-18" \
    -d nach_debit[mandate_details[frequency]]="MNTH" \
    -d redirect[return_url]="https://www.merchant.com/success"
{
    "type": "nach_debit",
    "nach_debit": {
        "bank_account_details":{
            "account_holder_name": "A JAIN",
            "account_number": "12345678",
            "account_type": "savings",
            "ifsc": "ICIC0000047"
        },
        "mandate_details": {
            "collection_amount": 10000,
            "first_collection_date": "2018-06-18",
            "frequency": "MNTH"
        }
    },
    "redirect": {
        "return_url": "https://www.merchant.com/thanks"
    }
}

Example Response 1

{
  "id": "SC004433221AA",
  "object": "source",
  "created": 1530224170,
  "customer_details": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "bank_account_details": {
        "account_holder_name": "A JAIN",
        "account_type": "savings",
        "ifsc": "ICIC0000047",
        "last4": "5678"
    },
    "category_code": null,
    "esign_mode": null,
    "mandate_details": {
        "collection_amount": 10000,
        "first_collection_date": "2018-06-18",
        "final_collection_date": null,
        "frequency": "MNTH",
        "maximum_amount": null,
        "occurrence_sequence_type": null
    }
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "show_lotuspay": null,
    "variant": null
  },
  "redirect": {
    "return_url": "https://www.merchant.com/thanks",
    "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D"
  }
  "subscription_details": {
    "amount": null,
    "count": null,
    "day_of_month": null,
    "interval": null,
    "interval_count": null,
    "month": null,
    "name": null,
    "start_date": null
  }
  "type": "nach_debit",
  "bank_account": "BA0011AABBCC22",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
  "subscription": null
}

Example Request 2

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d customer_details[name]="Amit Jain" \
    -d customer_details[mobile]="9123456789" \
    -d nach_debit[bank_account_details[account_holder_name]]="A JAIN" \
    -d nach_debit[bank_account_details[account_number]]="12345678" \
    -d nach_debit[bank_account_details[account_type]]="savings" \
    -d nach_debit[bank_account_details[ifsc]]="ICIC0000047" \
    -d nach_debit[reference1]="TEST" \
    -d redirect[return_url]="https://www.merchant.com/success" \
    -d subscription_details[amount]=10000 \
    -d subscription_details[count]=3 \
    -d subscription_details[interval]="month" \
    -d subscription_details[name]="TEST"
{
    "type": "nach_debit",
    "customer_details": {
        "name": "Amit Jain",
        "mobile": "9123456789"
    },
    "nach_debit": {
        "bank_account_details":{
            "account_holder_name": "A JAIN",
            "account_number": "12345678",
            "account_type": "savings",
            "ifsc": "ICIC0000047"
        },
        "reference1": "TEST"
    },
    "redirect": {
        "return_url": "https://www.merchant.com/success"
    },
    "subscription_details": {
        "amount": 10000,
        "count": 3,
        "interval": "month",
        "name": "TEST"
    }
}

Example Response 2

{
  "id": "SC004433221AA",
  "object": "source",
  "created": 1530224170,
  "customer_details": {
    "email": null,
    "mobile": "9123456789",
    "name": "Amit Jain",
    "pan": null,
    "phone": null
  },
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "bank_account_details": {
        "account_holder_name": "Amit Jain",
        "account_type": "savings",
        "ifsc": "ICIC0000047",
        "last4": "5678"
    },
    "category_code": "U099",
    "esign_mode": "otp",
    "mandate_details": {
        "collection_amount": null,
        "first_collection_date": null,
        "final_collection_date": null,
        "frequency": null,
        "maximum_amount": null,
        "occurrence_sequence_type": null
    }
    "nach_sponsor_bank": "TEST09999999",
    "nach_utility_code": "NACH00000000001111",
    "reference1": "TEST",
    "show_lotuspay": "true",
    "variant": "automatic"
  },
  "redirect": {
    "return_url": "https://www.merchant.com/success",
    "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D"
  }
  "subscription_details": {
    "amount": 10000,
    "count": 3,
    "day_of_month": null,
    "interval": "month",
    "interval_count": null,
    "month": null,
    "name": "TEST",
    "start_date": null
  }
  "type": "nach_debit",
  "bank_account": "BA0011AABBCC22",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
  "subscription": null
}

Creates a new source object. Main rules:

  1. You may enter mandate_details or subscription_details, but not both. If you enter subscription_details, the appropriate mandate variables will be determined for you and a subscription will be created along with the mandate.
  2. You may enter bank_account_details or bank_account, but not both. If you enter bank_account, the mandate will be created on that existing bank_account and the customer who owns that bank_account. If you enter bank_account_details, a new bank_account will be created. If you enter bank_account, you should not enter customer or customer_details.
  3. You may enter customer_details or customer, but not both. If you enter customer, the mandate will be created on that existing customer. If you enter customer_details, a new customer will be created.

ARGUMENTS

Argument Description
type REQUIRED The type of the source to create. Value is nach_debit. Does not appear in the mandate.
customer_details optional dictionary Information about the owner of the payment instrument. See child arguments in table below.
flow optional, default is redirect The authentication flow of the source. flow is redirect for NACH Debit. It is generally inferred unless a type supports multiple flows. Does not appear in the mandate.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Does not appear in the mandate.
nach_debit REQUIRED Information for the mandate to be created by the source object. See child arguments in the table below.
redirect REQUIRED dictionary Parameters required for the redirect flow. Required if the source is authenticated by a redirect (flow is redirect). See child arguments in the table below. Does not appear in the mandate.
subscription_details optional Information about the subscription to be created by the source. If subscription_details details are present, mandate_details must be empty, and vice versa. See child arguments in table below.

Child arguments for customer_details:

Note: Required if customer is not provided. If customer_details are present, customer must be empty, and vice versa.

Argument Description
email optional Customer's email address. Appears in the mandate.
mobile optional Customer's mobile number. Appears in the mandate. India mobile numbers must be 10 digits long and begin with 6, 7, 8 or 9.
name optional Customer's name. If no value is given then value is copied from the account_holder_name in bank_account_details. Does not appear in the mandate.
pan optional Customer's Permanent Account Number (Individual's tax ID in India). Appears in the mandate.
phone optional Customer's phone number. Appears in the mandate.

Child arguments for nach_debit:

Argument Description
bank_account_details optional dictionary Information about the bank account on which to create the mandate. See child arguments below. Required if bank_account is not given in the source. If bank_account is present, bank_account_details must be empty, and vice versa.
category_code optional, default is merchant's profile value assigned by LotusPay Four-digit NPCI code of the mandate category e.g. U099. See mandate category codes article in LotusPay Support site for more information. Appears in the mandate. RESTRICTED to Pro merchants.
esign_mode optional, default is otp The Aadhaar eSign authentication mode to be used for the nach_debit mandate when variant is esign. Either otp or biometric. Appears in the mandate. RESTRICTED to Pro merchants.
mandate_details optional dictionary Information about the mandate. Required if subscription_details are not provided. If mandate_details are given, subscription_details must be empty, and vice versa.
nach_utility_code optional, default is the merchant's default value, if any, else LotusPay's utility code The NACH utility code of the creditor of the mandate. An approved NACH relationship with this utility code must have already been set up by LotusPay. Appears in the mandate. RESTRICTED to Pro merchants.
nach_sponsor_bank optional, default is the merchant's default sponsor bank, if any, else LotusPay will allocate a sponsor bank at its discretion The 4-digit NACH bank code for the sponsor bank e.g. HDFC. An approved NACH sponsor bank profile must have already been set up by LotusPay. Appears in the mandate. RESTRICTED to Pro merchants.
reference1 optional, default is the id of the mandate that will be created by the source Merchant's own customer identifier. Appears in the mandate.
show_lotuspay optional, default is true Boolean indicating whether customer will be shown the LotusPay password page and authorisation page during the redirect flow. RESTRICTED to Pro merchants with approved payment pages.
variant optional, default is automatic The variant of the mandate to be created, either automatic, esign or npci_api. automatic means LotusPay will automatically assign the variant depending on the bank given or selected, with priority given to npci_api if the destination bank is live for that variant. RESTRICTED to Pro merchants. Currently, all sources will be automatic and all mandates will be esign. Does not appear in the mandate.

Child arguments for mandate_details:

Note: Required if subscription_details are not provided. If mandate_details details are provided, subscription_details must be empty, and vice versa.

Argument Description
collection_amount optional Fixed amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Required if maximum_amount is not given. Either maximum_amount or collection_amount can appear in the mandate (one or the other, not both). Appears in the mandate.
final_collection_date optional, default is null Final collection date (expiry date) of the mandate. Null entry means "Until Cancelled". Appears in the mandate.
first_collection_date REQUIRED First collection date (starte date) of the mandate. Appears in the mandate.
frequency REQUIRED The frequency with which debit transaction instructions are to be created and processed. Value can be ADHO, INDA,DAIL, WEEK, MNTH, BIMN, QURT, MIAN, YEAR. See mandate frequencies table for more information. Appears in the mandate.
maximum_amount optional Maximum amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Required if collection_amount is not given. Either maximum_amount or collection_amount can appear in the mandate (one or the other, not both). Appears in the mandate.
occurrence_sequence_type optional, default is RCUR Identifies the underlying transaction sequence as either recurring or one-off. Values must be "RCUR" or "OOFF". Appears in the mandate.

Child arguments for bank_account_details:

Note: Required if bank_account is not provided. Ifbank_account_details are present, bank_account must be empty, and vice versa.

Argument Description
account_holder_name REQUIRED The name of the person or business that owns the bank account. This must match the bank's records. Appears in the mandate.
account_number REQUIRED Customer's bank account number. Must be at least five characters in length. Appears in the mandate.
account_type REQUIRED Customer's bank account type. One of savings, current, nre, nro, or cc. Appears in the mandate.
ifsc REQUIRED Customer's bank branch IFSC code. Must be a real 11-digit IFSC code in the correct format. Appears in the mandate.

Child arguments for redirect:

Argument Description
return_url REQUIRED The URL you provide to redirect the customer back to you after they authenticated their payment. It can use your application URI scheme in the context of a mobile application. Does not appear in the mandate. LotusPay populates the return_url with GET parameters in the query-string (see the start of this section for details).

LotusPay populates the return_url with the following GET parameters in the query-string when returning your customer to your website:

e.g. ?livemode=false&mandate_id=MD0011AABBCC22&signing_status=true 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.

Child arguments for subscription (see the "Create a subscription" endpoint for detailed instructions):

Note: Required if mandate_details are not provided. If subscription_details are given, mandate_details must be empty, and vice versa.

Argument Description
amount REQUIRED The fixed amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Does not appear in the mandate.
count optional The total number of payments that should be taken by this subscription. If not specified, the subscription will continue until cancelled. Does not appear in the mandate.
day_of_month optional As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month. Does not appear in the mandate.
interval REQUIRED The unit of time between charge dates. One of day, week, month or year. Does not appear in the mandate.
interval_count optional, default value is 1 The number of intervals (specified in the interval property) between charge dates. For example, interval=month and interval_count=3 bills every three months. Must be greater than or equal to 1. Must result in at least one charge date within one year from creation. Does not appear in the mandate.
month optional, default is current month The name of the month on which to charge a customer. Must be lower case. Does not appear in the mandate.
name optional The name of the subscription. This will be set as the description on each payment created. Must not exceed 255 characters. Does not appear in the mandate.
start_date optional The date on which the first payment should be charged. Must be within one year of creation, and on or after the mandate's first_collection_date. When blank, this will be set to as soon as possible. Does not appear in the mandate.

Returns Returns a source object if valid arguments were provided.

The customer has to visit the url authorisation link in order to check and authorise the mandate. You can share the link independently, redirect the customer to it, or pass the customer into a webview from your mobile app (or use our mobile SDKs to do this). The customer needs to enter a password to continue. This password is either their mobile number or bank account number. If your customer is already logged into your web or mobile app, you can append the url with the password (e.g. ?mobile=9999123123) so that the customer can skip our password page and go directly to the mandate page.

Retrieve a source

GET https://api-test.lotuspay.com/v1/sources

Example Request

$ curl https://api-test.lotuspay.com/v1/sources/SC004433221AA \
  -u sk_test_xd22123sxlkadsf8wjbkx:

Example Response

{
  "id": "SC004433221AA",
  "object": "source",
  "created": 1530224170,
  "customer_details": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "bank_account_details": {
        "account_holder_name": "A JAIN",
        "account_type": "savings",
        "ifsc": "ICIC0000047",
        "last4": "5678"
    },
    "category_code": null,
    "esign_mode": null,
    "mandate_details": {
        "collection_amount": 10000,
        "first_collection_date": "2018-06-18",
        "final_collection_date": null,
        "frequency": "MNTH",
        "maximum_amount": null,
        "occurrence_sequence_type": null
    }
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "show_lotuspay": null,
    "variant": null
  },
  "redirect": {
    "return_url": "https://www.merchant.com/thanks",
    "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D"
  }
  "subscription_details": {
    "amount": null,
    "count": null,
    "day_of_month": null,
    "interval": null,
    "interval_count": null,
    "month": null,
    "name": null,
    "start_date": null
  }
  "type": "nach_debit",
  "bank_account": "BA0011AABBCC22",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
  "subscription": null
}

Retrieves an existing source object. Supply the unique source ID from a source creation request and LotusPay will return the corresponding up-to-date source object information.

ARGUMENTS

Argument Description
source REQUIRED The identifier of the source to be retrieved.

Returns Returns a source object if a valid identifier was provided.

Subscriptions

subscription objects create payment objects according to a schedule. The API allows you to retrieve your subscriptions. You can retrieve individual subscriptions as well as a list of all your subscriptions.

The following rules apply when specifying recurrence:

  1. If interval is year, then month and day_of_month are optional, although both are required if one is provided.
  2. If interval is month, then month is invalid and day_of_month is valid.
  3. If interval is week, then both month and day_of_month are invalid.

When a charge date falls on a non-business day, one of two things will happen:

The subscription object

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 1000,
  "cancel_reason": null,
  "cancelled_at": null,
  "count": 2,
  "created": 1530224170,
  "customer": "CU0012345ABCDE",
  "day_of_month": 23,
  "interval": "month",
  "interval_count": "2",
  "livemode": false,
  "mandate": "MD0011DD22RR33",
  "metadata": {
  },
  "month": null,
  "name": "Order 123",
  "plan": null,
  "start_date": "2018-07-02",
  "status": "active"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "subscription" String representing the object's type. Objects of the same type share the same value.
amount integer The fixed amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
cancel_reason boolean The mandate cancellation reason code for the mandate attached to the subscription. Present only if the subscription and mandate have been cancelled together.
cancelled_at timestamp If the subscription has been cancelled, the date of the cancellation.
count positive integer The total number of payments scheduled in this subscription. If not specified, the subscription will continue until cancelled.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
customer string The identifier of the customer who owns the subscription.
day_of_month integer As per RFC 2445. The day of the month to charge customers on. 1 to 28 or -1 to indicate the last day of the month.
interval string The unit of time between charge dates. One of day, week, month or year.
interval_count positive integer The number of intervals (specified in the interval property) between charge dates. For example, interval=month and interval_count=3 bills every three months.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
mandate string The identifier of the mandate that is creating payments for the subscription.
metadata hash Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
month string The name of the month on which to charge a customer.
name string The name of the subscription.
plan string The identifier of the subscription's plan, if any.
start_date date The date on which the first payment should be charged. Must be within one year of creation and on or after the mandate's first_collection_date and on or before its final_collection_date (if any).
status string The status of the subscription. One of pending_customer_approval, customer_approval_denied, active, finished and cancelled.

Create a subscription

POST https://api-test.lotuspay.com/v1/subscriptions

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d mandate="MD0011DD22RR33" \
   -d amount=1000 \
   -d count=2 \
   -d day_of_month=23 \
   -d interval="month" \
   -d name="Order 123" \
   -d start_date="2018-07-02"

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 1000,
  "cancel_reason": null,
  "cancelled_at": null,
  "count": 2,
  "created": 1530224170,
  "customer": "CU0012345ABCDE",
  "day_of_month": 23,
  "interval": "month",
  "interval_count": "2",
  "livemode": false,
  "mandate": "MD0011DD22RR33",
  "metadata": {
  },
  "month": null,
  "name": "Order 123",
  "plan": null,
  "start_date": "2018-07-02",
  "status": "active"
}

Creates a new subscription object. Subscriptions can be created on independent mandates i.e. those mandates which do not already have active subscriptions. One mandate can support only one subscription. There are complex rules on the interaction between mandates and subscriptions, and you must ensure that the mandate can support the subscription e.g. a mandate of frequency yearly cannot support a subscription which recurs monthly. See support article for more information.

ARGUMENTS

Argument Description
mandate REQUIRED The identifier of the associated mandate on which the subscription should create payments.
amount REQUIRED The fixed amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
interval REQUIRED The unit of time between charge dates. One of day, week, month or year.
count optional The total number of payments that should be taken by this subscription. If not specified, the subscription will continue until cancelled.
day_of_month optional As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.
interval_count optional, default value is 1 The number of intervals (specified in the interval property) between charge dates. For example, interval=month and interval_count=3 bills every three months. Must be greater than or equal to 1. Must result in at least one charge date within one year from creation.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
month optional, default is current month The name of the month on which to charge a customer. Must be lower case.
name optional The name of the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
start_date optional The date on which the first payment should be charged. Must be within one year of creation, and on or after the mandate's first_collection_date. When blank, this will be set as today or the mandate's first_collection_date, whichever is later.

Returns Returns a subscription object.

Retrieve a subscription

GET https://api-test.lotuspay.com/v1/subscriptions

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions/SB0044GG221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 1000,
  "cancel_reason": null,
  "cancelled_at": null,
  "count": 2,
  "created": 1530224170,
  "customer": "CU0012345ABCDE",
  "day_of_month": 23,
  "interval": "month",
  "interval_count": "2",
  "livemode": false,
  "mandate": "MD0011DD22RR33",
  "metadata": {
  },
  "month": null,
  "name": "Order 123",
  "plan": null,
  "start_date": "2018-07-02",
  "status": "active"
}

Retrieves an existing subscription object. Supply the unique subscription identifier.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the subscription to be retrieved.

Returns Returns a subscription object if a valid identifier was provided.

Cancel a subscription

GET https://api-test.lotuspay.com/v1/subscriptions

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions/SB0044GG221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X DELETE \
   -d cancel_reason="C001"

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 1000,
  "cancel_reason": "C001",
  "cancelled_at": "2018-07-05",
  "count": 2,
  "created": 1530224170,
  "customer": "CU0012345ABCDE",
  "day_of_month": 23,
  "interval": "month",
  "interval_count": "2",
  "livemode": false,
  "mandate": "MD0011DD22RR33",
  "metadata": {
  },
  "month": null,
  "name": "Order 123",
  "plan": null,
  "start_date": "2018-07-02",
  "status": "cancelled"
}

Cancels an existing subscription object. Supply the unique subscription identifier.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the subscription to be cancelled.
cancel_reason optional, default is C002 If you want to also cancel the mandate along with the subscription, specify the mandate cancellation reason code, either C001 (cancellation on customer request) or C002 (cancellation on merchant request). If this argument is null, the mandate will not be cancelled and will become an independent mandate. A new subscription can then be created on this mandate.

Returns Returns a cancelled subscription object if a valid identifier was provided.

List all subscriptions

GET https://api-test.lotuspay.com/v1/subscriptions

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions?limit=4 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -G

Example Response

{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
        {
            "id": "SB004433221AA"
        },
        {
            "id": "SB004433221BB"
        },
        {   
            "id": "SB004433221CC"
        },
        {   
            "id": "SB004433221DD"
        },
        {...
        }
  ]
}

You can see a list of your subscriptions. The subscriptions are returned sorted by creation date, with the most recent appearing first. You can use this API method and the limit parameter to page through subscriptions.

ARGUMENTS

Argument Description
customer optional Only return subscriptions for the customer specified by this identifier. If you pass this argument, you cannot also pass mandate.
limit optional, default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
mandate optional Only return subscriptions for the mandate specified by this identifier. If you pass this argument, you cannot also pass customer.

Returns A dictionary with a data property that contains an array of up to limit subscriptions. Passing an optional customer or mandate will result in filtering to subscriptions with only that exact object. Each entry in the array is a separate subscription object. If no more subscriptions are available, the resulting array will be empty.

MOBILE SDK

The LotusPay mobile SDKs for Android and iOS let your customers easily and securely authorise NACH Debit eMandates within a webview inside your mobile app.

After you integrate the SDK, the overall flow is:

  1. You use the LotusPay API or dashboard to generate a mandate/subscription/plan link.
  2. You pass the customer into the LotusPay webview with this link.
  3. The customer completes the authorisation process in the LotusPay webview.
  4. We pass control back to your mobile app with a success/failure response.

For more details about the customer's experience in the webview, visit our Knowledge Base. In brief:

The LotusPay mobile SDK allows for a seamless client-to-server secure check-out style experience for the user to authorise a mandate. For you to know the outcome of the mandate creation process, you can use the LotusPay API, webhook, dashboard or email notifications (or a combination of these). The API and webhook allow you to build custom flows in your web and mobile applications, although these features are not required for the actual mobile SDK integration.

Pre-requisites:

You can use live or test mandate/subscription/plan authorisation links in the mobile SDKs. Live links always begin with https://app.lotuspay.com whilst test links always begin with https://test.lotuspay.com.

Android SDK

Installation

dependencies {
implementation 'com.lotuspay:library:0.0.2'
}

Installing the LotusPay Android SDK is similar using Android Studio and IntelliJ. You don’t need to clone a repo or download any files. Just add the following to your project’s build.gradle file, inside the dependencies section.

Invocation

private void callLotusPay(String url) {
   Intent i = new Intent(MainActivity.this, LotusPay.class);
   i.putExtra("url", url);
   startActivityForResult(i, 101);
}

Call the LotusPay function with the mandate/subscription/plan link inserted in the code.

The customer will be redirected to the LotusPay webview where they will go through the mandate authorisation process.

SMS OTP auto-reading

<uses-permission-sdk-23 android:name="android.permission.READ_SMS"/>
<uses-permission-sdk-23 android:name="android.permission.RECEIVE_SMS"/>
<uses-permission android:name="android.permission.READ_SMS"/>

For Aadhaar eSign eMandates, when the customer receives the OTP by SMS, the LotusPay SDK will pre-fill and submit the OTP on the customer's behalf. Ensure you take necessary user permissions for this in the Android Manifest file as shown here.

NB: If the customer does not receive the OTP on the same device, they can manually enter the OTP. Auto-reading is only effective if the customer's inserted SIM card is of the same mobile number that is updated on their Aadhaar card.

Closure

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   super.onActivityResult(requestCode, resultCode, data);

   Toast.makeText(getApplicationContext(), data.getStringExtra("status") + ":Message:" + data.getStringExtra("message"), Toast.LENGTH_LONG).show();

}

When the process is complete, you will get a callback on the function shown here (look for requestCode 101).

If the mandate authorisation is successful, you will get a success message in status and failed otherwise. Ensure that you handle the response appropriately.

Test app

You can use our simple test app on your Android device to test the SDK. The test app has the SDK already added. Simply install the app, insert a valid live or test plan/subscription/mandate authorisation link, then click continue.

Simple test app

iOS SDK

Installation

Install the pod.

pod 'LotusPaySDK'

Import the framework in Objective-C:

import <LotusPaySDK/LotusPaySDK.h>

Import the framework in Swift:

import LotusPaySDK

Installing the LotusPay iOS SDK requires the CocoaPods dependency manager.

Start by installing the pod, then import the framework.

Invocation

In Objective-C:

[LotusPaySDK initializeWithPaymentURL: paymentURL onController: self completionBlock:^(BOOL success, NSString * message) {

}];

In Swift:

LotusPaySDK.initialize(withPaymentURL: paymentURL on: self) { [weak self] (success, message) in

}

Call the LotusPay function with the mandate/subscription/plan link inserted in the code.

The customer will be redirected to the LotusPay webview where they will go through the mandate authorisation process.

The function accepts three variables: 1. Payment URL: Mandate/subscription/plan link. 2. Controller: On which to present the view. 3. Call back block: Success (Boolean) and Message (String).

If the mandate authorisation is successful, you will get success, else failed. Ensure that you handle the response appropriately.

Closure

In Objective-C:

[LotusPaySDK dismiss: true];

In Swift:

LotusPaySDK.dismiss(true)

The function accepts one variable: 1. Animated: Depending on this value the dismiss happens with or without animation.