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:

Webhooks

Use webhooks to be notified about events that happen in a LotusPay account.

LotusPay can send webhook events that notify your application any time an event happens on your account. This is especially useful for events (like mandates being activated and many recurring billing events) that are not triggered by a direct API request. This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

You can register a webhook URL that we will notify any time an event happens in your account. When the event occurs (a successful payment is made on a customer’s subscription, a settlement is paid, a mandate is activated, etc.) LotusPay creates an Event object.

This event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. LotusPay then sends the event object, via an HTTP POST request, to the endpoint URL that you have defined in your account’s Webhooks settings.

When to use webhooks

Webhooks are necessary only for behind-the-scenes transactions. Many LotusPay requests (e.g. creating mandates or subscriptions) generate results that are reported synchronously to your code. These don’t require webhooks for verification.

NACH Debit requires using webhooks so that your integration can be notified about asynchronous changes to the status of mandate, payment and ach_debit objects.

You might also use webhooks as the basis to:

Configuring your Webhooks settings

Webhooks are configured in the Dashboard's Developers section. Here you can add a URL for receiving webhooks.

You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. The URL will be notified of all event types.

Your current environment — whether you're using a test or live LotusPay account — determines whether test events or live events are sent to your configured URL. If you want to send both live and test events to the same URL, you need to create two separate settings in each environment.

Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object.

Receiving webhooks with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, LotusPay will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to LotusPay that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. LotusPay will ignore any other information returned in the request headers or request body.

We will attempt to deliver your webhooks for up to three days with an exponential back off. Webhooks cannot be manually retried after this time, though you can query for the event to reconcile your data with any missed events.

Best practices

Before going live, test that your webhook is working properly. You can do so by using the test environment. To do this, add the endpoint to which test events should be sent. Next, click the Send a test webhook button. Understand that because these are dummy, test events, they will not map to real customers, mandates, payments, or other objects in your account.

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before LotusPay sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from LotusPay.

CORE RESOURCES

ACH Debits

RESTRICTED to Pro merchants

ach_debit objects represent ACH Debit transactions from a customer to a creditor, taken against a mandate. ach_debit objects are attached to customer and mandate objects. The API allows you to create and retrieve your ACH Debits. You can retrieve individual ACH debits as well as a list of all of your ACH debits.

You can create ACH Debits on any active NACH Debit mandate in NPCI's NACH Mandate Management System (MMS), regardless of whether the mandate was created in LotusPay, as long as you have an active NACH sponsor bank profile in LotusPay for the ACH Debit arguments that you pass.

The ACH Debits endpoint can only be used on mandates for which LotusPay is not processing payments. This means mandates for which LotusPay is acting as your technology partner and is not receiving your funds. If you're using LotusPay as a payments intermediary, you should use the Payments endpoint instead. See support article for more information.

The ACH debit object

Example Response

{
  "id": "ND004433221AA",
  "object": "ach_debit",
  "amount": 10000,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "nach_sponsor_bank": "HDFC",
  "nach_utility_code": "NACH00000000009999",
  "status": "confirmed",
  "umrn": "TEST000012345678"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "ach_debit" 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 ACH debit 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 ACH debit was taken from.
failure_code string Error code explaining reason for ACH debit failure if available (see the errors section for a list of codes).
failure_message string Message to user further explaining reason for ACH debit 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 ACH debit was or will be taken against.
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.
status string The status of the ACH debit, one of pending, submitted, cancelled, confirmed or failed.
umrn string The NACH unique mandate reference number of the mandate.

Create an ACH debit

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

Example Request

$ curl https://api-test.lotuspay.com/v1/ach_debits \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d amount=10000 \
   -d mandate="MD0011DD22RR33"
{
  "amount": 10000,
  "mandate": "MD0011DD22RR33"
}

Example Response

{
  "id": "ND004433221AA",
  "object": "ach_debit",
  "amount": 10000,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "nach_sponsor_bank": "HDFC",
  "nach_utility_code": "NACH00000000009999",
  "status": "collected",
  "umrn": "TEST000012345678"
}

Creates a new ACH debit object.

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

ACH debits can be created against LotusPay mandates with status of: pending, pending_submission, submitted, acknowledged and active. ACH debits can be created against any non-LotusPay mandates, although you should ensure that the mandate is in an active status in MMS else the ACH debit will fail (LotusPay does not validate ACH debits on non-LotusPay mandates).

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 ACH debit should be collected. If not specified, the ACH debit will be collected as soon as possible. If the mandate is a LotusPay mandate, the charge_date 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 ACH debit will be collected on the same day, else it will be rolled forward by LotusPay.
mandate optional The identifier of the mandate against which this ACH debit should be collected. Either id or umrn must be supplied (one or the other, not both).
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.
nach_sponsor_bank optional 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. Required if the ACH debit is on a non-LotusPay mandate.
nach_utility_code optional 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. Required if the ACH debit is on a non-LotusPay mandate.
umrn optional The NACH Unique Mandate Reference Number of the mandate against which this ACH debit should be collected. Either id or umrn must be supplied (one or the other, not both).

Returns Returns a newly created ACH debit object.

Retrieve an ACH debit

GET https://api-test.lotuspay.com/v1/ach_debits/{ID}

Example Request

$ curl https://api-test.lotuspay.com/v1/ach_debits/ND004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:
Not applicable

Example Response

{
  "id": "ND004433221AA",
  "object": "ach_debit",
  "amount": 20025,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "nach_sponsor_bank": "HDFC",
  "nach_utility_code": "NACH00000000009999",
  "status": "confirmed",
  "umrn": "TEST000012345678"
}

Retrieves an existing ACH debit object. Supply the unique ACH debit identifer.

ARGUMENTS

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

Returns Returns an ACH debit object if a valid identifier was provided.

Cancel an ACH debit

POST https://api-test.lotuspay.com/v1/ach_debits/{ID}/cancel

Example Request

$ curl https://api-test.lotuspay.com/v1/ach_debits/ND004433221AA/cancel \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X POST
Not applicable

Example Response

{
  "id": "ND004433221AA",
  "object": "ach_debit",
  "amount": 20025,
  "charge_date": "2017-06-01",
  "created": 1530224170,
  "customer": "CU001234DDAA",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "mandate": "MD0011DD22RR33",
  "nach_sponsor_bank": "HDFC",
  "nach_utility_code": "NACH00000000009999",
  "status": "cancelled",
  "umrn": "TEST000012345678"
}

Cancels an existing ACH debit object. Supply the unique ACH debit identifer. The ACH debit must be in a cancellable status, i.e. pending. ACH debits cannot be cancelled once they are submitted to the banking system.

ARGUMENTS

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

Returns Returns a cancelled ACH debit object if a valid identifier was provided.

List all ACH debits

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

Example Request

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

Example Response

{
  "object": "list",
  "url": "/v1/ach_debits",
  "has_more": false,
  "data": [
        {
            "id": "ND004433221AA"
        },
        {
            "id": "ND004433221BB"
        },
        {
            "id": "ND004433221CC"
        },
        {...
        }
  ]
}

You can see a list of your ACH debits. The ACH debits 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 ACH debits.

ARGUMENTS

Argument Description
customer optional Only return ACH debits for the customer specified by this identifier. If you pass this argument, you cannot also pass mandate 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 ACH debits for the mandate specified by this identifier. If you pass this argument, you cannot also pass customer or umrn.
umrn optional Only return ACH debits for the umrn specified by this identifier. If you pass this argument, you cannot also pass customer or mandate.

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

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 of your 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/bank_accounts/BA004433221AA/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/{ID}/bank_accounts/{ID}

Example Request

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

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/bank_account/BA004433221AA/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/{ID}/bank_accounts

Example Request

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

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/{ID}

Example Request

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

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
Not applicable

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.

Events

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a payment succeeds, we create a payment.confirmed event; and when a payment fails, we create a payment.failed event. Note that many API requests may cause multiple events to be created. For example, if you create a new subscription for a customer, you will receive both a subscription.created event and a payment.created event.

Events occur when the state of another API resource changes. The state of that resource at the time of the change is embedded in the event's data field. For example, a payment.confirmed event will contain a payment, and a mandate.failed event will contain a mandate.

As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. We also have a separate webhooks system for sending the Event objects directly to an endpoint on your server. Webhooks are managed in your account settings, and our Support article will help you get set up.

NOTE: Right now, access to events through the Retrieve Event API is guaranteed only for 30 days.

The event object

Example Response

{
  "id": "EV004433221AA",
  "object": "event",
  "created": 1530224170,
  "data": {
    "id": "CU004433221AA",
    "object": "customer",
    "created": 1530224170,
    ...
    }
  "livemode": false,
  "type": "customer.created"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "event" 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.
data string Object containing data associated with the event. See child attributes below.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
type string Description of the event (e.g., customer.created or payment.failed).

Child attributes for data:

Attribute Description
object hash Object containing the API resource relevant to the event. For example, a customer.created event will have a full customer object as the value of the object key.

Retrieve an event

GET https://api-test.lotuspay.com/v1/events/{ID}

Example Request

$ curl https://api-test.lotuspay.com/v1/events/EV004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82:
Not applicable

Example Response

{
  "id": "EV004433221AA",
  "object": "event",
  "created": 1530224170,
  "data": {
    "id": "CU004433221AA",
    "object": "customer",
    "created": 1530224170,
    ...
    }
  "livemode": false,
  "type": "customer.created"
}

Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.

ARGUMENTS

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

Returns Returns an event object if a valid identifier was provided. All events share a common structure, detailed to the right. The only property that will differ is the data property.

In each case, the data dictionary will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a customer.created event will have the same information as retrieving the relevant customer would.

In cases where the attributes of an object have changed, data will also contain a dictionary containing the changes.

List all events

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

Example Request

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

Example Response

{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
        {
            "id": "EV004433221AA"
        },
        {
            "id": "EV004433221BB"
        },
        {
            "id": "EV004433221CC"
        },
        {
            "id": "EV004433221DD"
        },
        {...
        }
  ]
}

List events, going back up to 30 days. The events 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 events.

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 events, starting after event starting_after. Each entry in the array is a separate event object. If no more events are available, the resulting array will be empty. This request should never return an error.

Types of events

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

You'll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against.

EVENT

Type Description
ach_debit.cancelled describes an ACH debit Occurs whenever an ACH Debit is cancelled.
ach_debit.confirmed describes an ACH debit Occurs whenever an ACH Debit is confirmed.
ach_debit.failed describes an ACH debit Occurs whenever an ACH Debit fails.
ach_debit.pending describes an ACH debit Occurs whenever an ACH Debit is created.
ach_debit.submitted describes an ACH debit Occurs whenever an ACH Debit is submitted.
customer.pending describes a customer Occurs whenever a customer is created.
customer.active describes a customer Occurs whenever a customer has an active mandate.
customer.inactive describes a customer Occurs whenever a customer has an no active mandates.
mandate.acknowledged describes a mandate Occurs whenever a mandate is acknowledged.
mandate.active describes a mandate Occurs whenever a mandate is activated.
mandate.cancelled describes a mandate Occurs whenever a mandate is cancelled.
mandate.failed describes a mandate Occurs whenever a mandate fails.
mandate.expired describes a mandate Occurs whenever a mandate is expired.
mandate.pending describes a mandate Occurs whenever a mandate is created.
mandate.pending_submission describes a mandate Occurs whenever a mandate is authorised.
mandate.submitted describes a mandate Occurs whenever a mandate is submitted.
mandate.withdrawn describes a mandate Occurs whenever a mandate is withdrawn.
payment.cancelled describes a payment Occurs whenever a payment is cancelled.
payment.confirmed describes a payment Occurs whenever a payment is confirmed.
payment.pending_submission describes a payment Occurs whenever a payment is created.
payment.failed describes a payment Occurs whenever a payment fails.
payment.settled describes a payment Occurs whenever a payment is settled.
payment.submitted describes a payment Occurs whenever a payment is submitted.
settlement.pending describes a settlement Occurs whenever a settlement is created.
settlement.processing describes a settlement Occurs whenever a settlement is processing.
settlement.settled describes a settlement Occurs whenever a settlement is paid out.
subscription.active describes a subscription Occurs whenever a subscription is created.
subscription.cancelled describes a subscription Occurs whenever a subscription is cancelled.
subscription.finished describes a subscription Occurs whenever a subscription finishes.

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 of your mandates.

To make mandates, use the source endpoint.

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.

Create a mandate

To create a mandate, use the source endpoint.

Retrieve a mandate

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

Example Request

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

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

POST https://api-test.lotuspay.com/v1/mandates/{ID}/cancel

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/MD004433221AA/cancel \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X POST \
   -d cancel_reason="C001"
{
  "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. Supply the unique LotusPay mandate identifer or the UMRN. Internal mandates are those that have been created in LotusPay. External mandates are those that have not. To cancel an internal mandate, 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). Any external mandate (both eMandates and physical mandates) can be cancelled using this endpoint.

ARGUMENTS

Argument Description
cancel_reason optional, default is C002 The cancellation reason. Either C001 (cancellation on customer request) or C002 (cancellation on merchant request).
id optional The identifier of the internal mandate to be cancelled. Either id or umrn must be supplied.
nach_sponsor_bank optional, default is merchant's default sponsor bank The 4-digit NACH bank code for the sponsor bank e.g. HDFC. An active NACH sponsor bank profile must have already been set up by LotusPay. Required if the the mandate to be cancelled is an external mandate or is made with any utility code other than LotusPay's.
nach_utility_code optional The NACH utility code of the creditor of the mandate. An active NACH profile with this utility code must have already been set up by LotusPay. Required if the the mandate to be cancelled is an external mandate or is made with any utility code other than LotusPay's.
umrn optional The NACH Unique Mandate Reference Number of the internal or external mandate to be cancelled. For internal mandates, umrn is not be present until the mandate has reached acknowledged status. If LotusPay does not recognise the umrn as being for an internal mandate, the request is treated as if it is for an external mandate. For external mandates, LotusPay does not validate the umrn. Either id or umrn must be supplied.

Returns Returns a withdrawn/cancelled mandate if a valid identifier was provided. For internal mandates, if the status was pending or pending_submission, the status will change to withdrawn; and if the status was submitted, acknowledged or active, the status will not immediately change but the cancel_status will change to cancellation_requested. For external mandates, the cancel_status will be 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
Not applicable

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.

NACH Banks

nach_bank objects represent banks participating in the NACH system. The API allows you to retrieve NACH banks. You can retrieve individual NACH banks as well as a list of all NACH banks. This database is updated on the first working day of each month, and may be updated more frequently if any major changes require publishing.

This endpoint is useful for you to determine what type of mandate to create for a customer banking with a particular bank. For example, if your customer is banking with Bank A, you might query to see if Bank A is enabled for the ACH Debit payment system, and especially to see if Bank A is enabled for the eSign mandate variant of ACH Debit. If it is enabled, you would proceed using the Source API endpoint.

The NACH bank object

Example Response

{
    "id": "YESB",
    "object": "nach_bank",
    "ach_dr": true,
    "display_name": "Yes Bank",
    "ifsc": "YESB0000001",
    "name": "YES BANK",
    "variant_esign": true,
    "variant_api": false
}

ATTRIBUTES

Attribute Description
id string NACH four-digit identifier of the bank.
object string, value is "nach_bank" String representing the object’s type. Objects of the same type share the same value.
ach_dr boolean True if the NACH bank is enabled for ACH Debit, else false.
display_name string The display name of the NACH bank in LotusPay.
ifsc string The central NACH branch IFSC code of the NACH bank.
name string The name of the NACH bank as per NPCI records.
variant_esign boolean True if the NACH bank is enabled for the eSign variant of eMandates, else false.
variant_api boolean True if the NACH bank is enabled for the NPCI API variant of eMandates, else false.

Retrieve an NACH bank

GET https://api-test.lotuspay.com/v1/nach_banks/{ID}

Example Request

$ curl https://api-test.lotuspay.com/v1/nach_banks/YESB \
   -u sk_test_XjIHowXWSI23uvjepz2X82:
Not applicable

Example Response

{
    "id": "YESB",
    "object": "nach_bank",
    "ach_dr": true,
    "display_name": "Yes Bank",
    "ifsc": "YESB0000001",
    "name": "YES BANK",
    "variant_esign": true,
    "variant_api": false
}

Retrieves an existing NACH bank object. Supply the unique NACH bank identifer in the url.

This endpoint has no arguments.

Returns Returns an NACH bank object if a valid identifier was provided in the url.

List all NACH banks

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

Example Request

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

Example Response

{
  "object": "list",
  "url": "/v1/nach_banks",
  "has_more": false,
  "data": [
        {
            "id": "AACX"
        },
        {
            "id": "ABCX"
        },
        {
            "id": "ABDX"
        },
        {...
        }
  ]
}

You can see a list of NACH banks. The NACH banks are returned sorted alphabetically by their four letter code. You can use this API method and the limit parameter to page through NACH banks.

ARGUMENTS

Argument Description
filter optional A filter that returns only those NACH banks that support ach_dr (ACH Debit), variant_api (NPCI API variant of eMandates) or variant_esign (eSign variant of eMandates).
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 NACH banks. Passing an optional filter will result in filtering to NACH banks enabled for only that type of mandate. Each entry in the array is a separate NACH bank object. If no more NACH banks are available, the resulting array will be empty.

Payments

payment objects represent payments from a customer to a creditor, taken against a mandate, and with payment processing by LotusPay. payment objects are attached to customer, mandate and settlement objects and can also be attached to subscription objects. The API allows you to create and retrieve your payments. You can retrieve individual payments as well as a list of all of your payments.

The Payments API can only be used on mandates for which LotusPay is processing payments. This means mandates for which LotusPay is acting as a payments intermediary and is receiving funds before paying out to you. If you're using LotusPay as a technology partner, you should use the ACH Debits endpoint instead. See support article for more information.

The payment object

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 10000,
  "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": "confirmed",
  "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.
mandate string The identifier of the mandate this payment was or will be taken against.
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.
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 payment 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-test.lotuspay.com/v1/payments

Example Request

$ curl https://api-test.lotuspay.com/v1/payments \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d amount=10000 \
   -d mandate="MD0011DD22RR33"
{
    "amount": 1000,
    "mandate": "MD0011DD22RR33"
}

Example Response

{
  "id": "PA004433221AA",
  "object": "payment",
  "amount": 10000,
  "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": "confirmed",
  "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.
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).
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.
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/{ID}

Example Request

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

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

POST https://api-test.lotuspay.com/v1/payments/{ID}

Example Request

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

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 
Not applicable

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
customer optional Only return payments for the customer specified by this identifier. If you pass this argument, you cannot also pass 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 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 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 customer, mandate or subscription.

Returns A dictionary with a data property that contains an array of up to limit payments. Passing an optional 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 of your 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/{ID}

Example Request

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

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
Not applicable

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 requests to make 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. You can also create partial sources: these initially contain no bank account details. Partial sources create a mandate only when the customer enters their bank account details in the web form.

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

The overall flow is:

  1. a) You create a source with fully pre-filled data. LotusPay returns a mandate with an authorisation link in url, along with a customer, bank_account and possibly a subscription. Or: b) You create a source with partial data, excluding bank account details. You want the customer to enter their own bank account details. LotusPay returns a form link in url and nothing else.
  2. Your customer visits the link, enters their bank account details if not already given, and goes through the mandate authorisation redirect flow. This displays a status to the customer and sends 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 or ach_debit at this point. If you created a subscription mandate, the subscription will automatically create them for you.

If you want LotusPay to send the url link to your customer, you can use the send_email argument and an email will instantly be sent to your customer. The display name of the From email address will be your company's trading name. Otherwise, you can share the url link independently via email/SMS/chat etc., redirect the customer to the link from your website, or pass the customer into a webview from your mobile app (or use our mobile SDKs to do this).

If the mandate is pre-filled with bank account details, the customer needs to enter a password when they land on the url page. This password is either their mobile number or bank account number. If they enter the wrong password 10 times, the link will be disabled (you can re-enable it from the dashboard). Pro Merchants can optionally override the password page if your customer is already logged into your web or mobile app. Contact us to enable this.

If you have built your own custom payment page approved by LotusPay, you can optionally set show_lotuspay to false, and the customer will not see the LotusPay mandate authorisation page - they will directly see the next page (the eSign gateway page, if variant is esign). The show_lotuspay argument is restricted to Pro merchants with approved payment pages. Contact us for more information.

If variant is esign, the customer will be redirected to the eSign gateway page where they must complete Aadhaar eSign. See our Knowledge Base at https://support.lotuspay.com for screenshots and more information regarding the user's experience.

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-12-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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE"
  },
  "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 generally be empty (unless mandate's maximum_amount has also been given).
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 full mandate_details details are present, subscription_details will be empty.
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 null or 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.
send_email boolean Boolean indicating whether LotusPay should send the customer an email invitation containing the mandate authorisation url.
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):

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 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 - Independent mandate

$ 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-12-18" \
    -d nach_debit[mandate_details[frequency]]="MNTH" \
    -d redirect[return_url]="https://www.lotuspay.com/"
{
    "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-12-18",
            "frequency": "MNTH"
        }
    },
    "redirect": {
        "return_url": "https://www.lotuspay.com/"
    }
}

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-12-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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE"
  },
  "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 - Partial source (customer to enter own bank account details)

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[mandate_details[collection_amount]]=10000 \
    -d nach_debit[mandate_details[first_collection_date]]="2018-12-18" \
    -d nach_debit[mandate_details[frequency]]="MNTH" \
    -d redirect[return_url]="https://www.lotuspay.com/"
{
    "type": "nach_debit",
    "nach_debit": {
        "mandate_details": {
            "collection_amount": 10000,
            "first_collection_date": "2018-12-18",
            "frequency": "MNTH"
        }
    },
    "redirect": {
        "return_url": "https://www.lotuspay.com/"
    }
}

Example Response 2

{
  "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": null,
        "account_type": null,
        "ifsc": null,
        "last4": null
    },
    "category_code": null,
    "esign_mode": null,
    "mandate_details": {
        "collection_amount": 10000,
        "first_collection_date": "2018-12-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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/form/AL00AABBCCDDEE"
  },
  "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": null,
  "customer": null,
  "mandate": null,
  "subscription": null
}

Example Request 3 - Independent mandate on existing bank account

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[mandate_details[collection_amount]]=10000 \
    -d nach_debit[mandate_details[first_collection_date]]="2018-12-18" \
    -d nach_debit[mandate_details[frequency]]="MNTH" \
    -d redirect[return_url]="https://www.lotuspay.com/"
    -d bank_account="BA0011AABBCC22"
{
    "type": "nach_debit",
    "nach_debit": {
        "mandate_details": {
            "collection_amount": 10000,
            "first_collection_date": "2018-12-18",
            "frequency": "MNTH"
        }
    },
    "redirect": {
        "return_url": "https://www.lotuspay.com/"
    },
    "bank_account": "BA0011AABBCC22"
}

Example Response 3

{
  "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": null,
        "account_type": null,
        "ifsc": null,
        "last4": null
    },
    "category_code": null,
    "esign_mode": null,
    "mandate_details": {
        "collection_amount": 10000,
        "first_collection_date": "2018-12-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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE"
  },
  "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 4 - Subscription mandate

$ 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.lotuspay.com/" \
    -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.lotuspay.com/"
    },
    "subscription_details": {
        "amount": 10000,
        "count": 3,
        "interval": "month",
        "name": "TEST"
    }
}

Example Response 4

{
  "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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE"
  },
  "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": "SB0011AABBCC22"
}

Creates a new source object. Main rules:

1) You may give mandate_details, subscription_details or subscription_details with a mandate maximum_amount.

2) You may give bank_account_details, bank_account, or neither.

Note: If you give bank_account_details, you should not give bank_account, and vice versa.

3) You may give customer_details, customer, or neither.

Note: If you give customer_details, you should not give customer, and vice versa.

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 given, the only mandate_details argument that can be given is maximum_amount. See child arguments in table below.
bank_account optional The unique identifier of the bank account on which to create the mandate, or a bank account token.
customer optional The unique identifier of the customer on which to create the mandate.

Child arguments for customer_details:

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. This can be any mobile number - it need not be the mobile number on the customer's Aadhaar.
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 all mandate_details are given, subscription_details can not be given.
nach_utility_code optional, default is the merchant's NACH utility code with the NACH sponsor bank passed, if any, else LotusPay's utility code The NACH utility code of the creditor of the mandate. An approved NACH profile with this utility code must be in place with the nach_sponsor_bank, else LotusPay will automatically allocate its own NACH profile (if any) for this sponsor bank. 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 profile with this sponsor bank must be in place with the nach_utility_code, else LotusPay will automatically allocate its own NACH profile (if any) for this sponsor bank. 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 mandate 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:

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:

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. Letters must be capitalised. 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).
send_email optional, default is false Boolean indicating whether LotusPay should send the customer an email invitation containing the mandate authorisation url. Requires customer or customer_details to have email. The email will have from display name as merchant's name, from email address as support@lotuspay.com, and reply-to email address as merchant's email address.

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):

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 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.

Retrieve a source

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

Example Request

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

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-12-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.lotuspay.com/",
    "send_email": false,
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE"
  },
  "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 payments or ACH debits according to a schedule. The API allows you to retrieve your subscriptions. You can retrieve individual subscriptions as well as a list of all of your subscriptions.

If the NACH profile of the subscription's mandate is crediting to merchant's bank account, the subscription creates ACH debits. If the NACH profile of the subscription's mandate is creditng to LotusPay, the subscription creates payments. If the NACH profile has no creditor bank account, subscription cannot be created.

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 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/ACH debits 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 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 on which the subscription is creating payments/ACH debits.
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/ACH debit 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"
{
    "mandate": "MD0011DD22RR33",
    "amount": 1000,
    "count": 2,
    "day_of_month": 23,
    "interval": "month",
    "name": "Order 123",
    "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 subscription on an existing mandate.

ARGUMENTS

Argument Description
mandate REQUIRED The identifier of the associated mandate on which the subscription should create payments/ACH debits. Mandate's status must be pending, pending_submission, submitted, acknowledged or active. Mandate should not have any existing pending_customer_approval or active subscription attached to it. Mandate should have maximum_amount, not collection_amount. Mandate's frequency must be ADHO. Mandate's NACH profile must have a creditor bank account.
amount REQUIRED The amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Must be less than or equal to mandate's maximum_amount and Rs 1 crore (for physical mandates) and Rs 1 lakh (for eMandates).
interval REQUIRED The unit of time between charge dates. One of week, month or year. Must result in at least one charge date within the next one year. All arising charge dates must fall between mandate's first_collection_date and final_collection_date.
count optional The total number of payments/ACH debits that should be taken by this subscription. If not specified, the subscription will continue until cancelled. The resulting final charge date must be on or before the mandate's final_collection_date.
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 the next one year. All arising charge dates must fall between mandate's first_collection_date and final_collection_date.
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/ACH debit 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/{ID}

Example Request

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

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

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

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions/SB0044GG221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -X POST \
   -d cancel_reason="C001"
{
    "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
Not applicable

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.

Tokens

Tokenisation is the process LotusPay uses to collect sensitive bank account details, or personally identifiable information (PII), directly from your customers in a secure manner. A token representing this information is returned to your server to use. You should use our JavaScript element to perform this process, client-side. This ensures that no sensitive bank account data touches your server, and allows your integration to operate in a certifiable way.

If you cannot use client-side tokenisation, you can also create tokens using the API without an API key. Keep in mind that if your integration uses this method, you are responsible for any compliance that may be required. Unlike with client-side tokenisation, your customer's information is not sent directly to LotusPay, so we cannot determine how it is handled or stored.

Tokens cannot be stored or used more than once. Tokens expire 30 minutes after they are created.

The token object

Example Response

{
    "id": "btok_MhIZEAGfQsxqYPGvm2bSn3mX",
    "object": "token",
    "bank_account": {
        "account_holder_name": "AMIT JAIN",
        "account_type": "savings",
        "ifsc": "ICIC0000043",
        "last4": "5678"
    },
    "created": 1536670980,
    "livemode": true,
    "type": "bank_account"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "token" String representing the object's type. Objects of the same type share the same value.
bank_account optional hash Hash describing the bank account. See child table below.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
type string Type of the token: bank_account.
used boolean Whether this token has already been used (tokens can be used only once).
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.
ifsc string Branch IFSC code.
last4 string Last four digits of the bank account number.

Create a token

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

Example Request

$ curl https://api-test.lotuspay.com/v1/tokens \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d bank_account[ifsc]="ICIC0000043" \
   -d bank_account[account_holder_name]="AMIT JAIN" \
   -d bank_account[account_type]="savings" \
   -d bank_account[account_number]="12345678"
{
    "bank_account":
    {
        "ifsc": "ICIC0000043", 
        "account_holder_name": "AMIT JAIN", 
        "account_type": "savings", 
        "account_number": "12345678"
    }
}

Example Response

{
    "id": "btok_MhIZEAGfQsxqYPGvm2bSn3mX",
    "object": "token",
    "bank_account": {
        "account_holder_name": "AMIT JAIN",
        "account_type": "savings",
        "ifsc": "ICIC0000043",
        "last4": "5678"
    },
    "created": 1536670980,
    "livemode": true,
    "type": "bank_account"
}

Creates a single-use token that represents a bank account’s details. This token can be used in place of a bank account dictionary with any API method. These tokens can be used only once.

ARGUMENTS

Argument Description
bank_account optional The bank account this token will represent. See child table below.

Child arguments for bank_account:

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.
account_number REQUIRED Customer's bank account number. Must be at least five characters in length.
account_type REQUIRED Customer's bank account type. One of savings, current, nre, nro, or cc.
ifsc REQUIRED Customer's bank branch IFSC code. Must be a real 11-digit IFSC code in the correct format. Letters must be capitalised.

Returns Returns the created bank account token if successful. Otherwise, this call returns an error.

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.