NAV Navbar
curl http

TOPICS

Introduction

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

The LotusPay NACH Debit 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 and the mandate object exists (either internal or imported external).

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": "HDFC000012345678"
}

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": "HDFC000012345678"
}

Creates a new ACH debit object.

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

ACH debits can be created against mandates with status of: pending, pending_submission, submitted, acknowledged and active. ACH debits can be created on both internal mandates (those that were created in LotusPay) and external mandates (those that were created elsewhere and imported into LotusPay). For external mandates, you should ensure that the mandate is in an active status in NPCI NACH MMS else the ACH debit will fail (LotusPay does not validate ACH debits on external mandates).

ARGUMENTS

Argument Description
amount REQUIRED Amount in paisa (one hundredths of a Rupee). Must be less than or equal to the mandate's maximum_amount or equal to the mandate's fixed_amount. Validated for internal mandates.
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. Must be on or after the mandate’s first_collection_date and on or before the mandate's final_collection_date (validated for internal mandates). 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 mandate 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 ACH debit should be collected. Either mandate 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": "HDFC000012345678"
}

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

ARGUMENTS

Argument Description
ach_debit 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": "HDFC000012345678"
}

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

Create a bank account

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

Example Request

$ curl https://api-test.lotuspay.com/v1/customers/CU004433221AA/bank_accounts/ \
   -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"
}

When you create a new bank account, you must specify a Customer object on which to create it.

ARGUMENTS

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.
customer REQUIRED The identifier of the customer on which to create the bank account.
ifsc REQUIRED Customer's bank branch 11-digit IFSC code.
metadata optional A set of key/value pairs that you can attach to a bank account object. It can be useful for storing additional information about the bank account in a structured format.

Returns Returns a bank account object.

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

Create a customer

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

Example Request

$ curl https://api-test.lotuspay.com/v1/customers/CU004433221AA \
    -u sk_test_XjIHowXWSI23uvjepz2X82:
    -d email="test@lotuspay.com" \
    -d mobile="+91-9123456789" \
    -d name="Amit Jain" \
    -d pan="ABCDE1234A"
{
    "email": "test@lotuspay.com",
    "mobile": "+91-9123456789",
    "name": "Amit Jain",
    "pan": "ABCDE1234A"
}

Example Response

{
  "id": "CU004433221AA",
  "object": "customer",
  "bank_accounts": {
    "object": "list",
    "data": [
    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/bank_accounts"
  },
  "created": 1530224170,
  "description": null,
  "email": "test@lotuspay.com",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "pan": "ABCDE1234A",
  "phone": "9123456789",
  "subscriptions": {
    "object": "list",
    "data": [
    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/subscriptions"
  }
}

Creates a new customer object.

ARGUMENTS

Argument Description
email optional Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to 512 characters. This will be unset if you POST an empty value.
metadata optional A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format.
mobile optional Customer phone (including extension). This will be unset if you POST an empty value.
name REQUIRED Customer name. This will be unset if you POST an empty value.
pan optional The customer’s tax Permanent Account Number (PAN) number. This will be unset if you POST an empty value.

Returns Returns a customer object if valid arguments were provided.

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

Internal mandates are those that were created in LotusPay. External mandates are those that were created elsewhere.

To create mandates, use the source endpoint.

The mandate object

Example Response

{
  "id": "MD004433221AA",
  "object": "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": "HDFC BANK",
  "creditor_agent_mmbid": "HDFC0999999",
  "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": "YES BANK",
  "debtor_agent_mmbid": "YESB0000001",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "HDFC BANK",
  "instructing_agent_mmbid": "HDFC0999999",
  "instructed_agent": "YES BANK",
  "instructed_agent_mmbid": "YESB0000001",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate"
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "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. HDFC 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.
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 physical or esign and is always debtor_agent_mmbid if variant is emandate.
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 physical or esign and is always creditor_agent_mmbid if variant is emandate.
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 physical or emandate.

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": "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": "HDFC BANK",
  "creditor_agent_mmbid": "HDFC0999999",
  "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": "YES BANK",
  "debtor_agent_mmbid": "YESB0000001",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "HDFC BANK",
  "instructing_agent_mmbid": "HDFC0999999",
  "instructed_agent": "YES BANK",
  "instructed_agent_mmbid": "YESB0000001",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate"
}

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

ARGUMENTS

Argument Description
mandate REQUIRED The identifier or umrn of the mandate to be retrieved. The NACH unique mandate reference number attribute will not be present until the mandate has reached acknowledged status.

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": "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": "HDFC BANK",
  "creditor_agent_mmbid": "HDFC0999999",
  "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": "YES BANK",
  "debtor_agent_mmbid": "YESB0000001",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "instructing_agent": "HDFC BANK",
  "instructing_agent_mmbid": "HDFC0999999",
  "instructed_agent": "YES BANK",
  "instructed_agent_mmbid": "YESB0000001",
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "show_lotuspay": true,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate"
}

Cancels an existing mandate. Supply the unique LotusPay mandate identifer or the UMRN. 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 mandate's most recently updated 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.
umrn optional The NACH Unique Mandate Reference Number of the internal or external mandate to be cancelled. For internal mandates, umrn is not 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 validates the umrn to be unique for the merchant. 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.

Import an external mandate

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

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/MD004433221AA \
    -u sk_test_XjIHowXWSI23uvjepz2X82 \
    -d creditor_agent_mmbid="HSBC" \
    -d nach_utility_code="NACH00000000001111" \
    -d umrn="HSBC6000000000272000" \
{
    "creditor_agent_mmbid": "HDFC",
    "nach_utility_code": "NACH00000000001111",
    "umrn": "HSBC6000000000272000"
}

Example Response

{
  "id": "MD004433221AA",
  "object": "mandate",
  "account_holder_name": null,
  "account_last4": null,
  "account_type": null,
  "amend_status": null,
  "bank_account": null,
  "cancel_status": null,
  "cancel_reason": null,
  "category_code": null,
  "collection_amount": null,
  "created": 1530224170,
  "creditor": "LOTUSPAY SOLUTIONS PVT LTD",
  "creditor_agent": "HFDC BANK",
  "creditor_agent_mmbid": "HDFC0999999",
  "customer": null,
  "customer_email": null,
  "customer_mobile": null,
  "customer_name": null,
  "customer_pan": null,
  "customer_phone": null,
  "date_acknowledged": null,
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": null,
  "debtor_agent": "HSBC",
  "debtor_agent_mmbid": null,
  "failure_reason": null,
  "first_collection_date": null,
  "final_collection_date": null,
  "frequency": null,
  "instructing_agent": null,
  "instructing_agent_mmbid": null,
  "instructed_agent": null,
  "instructed_agent_mmbid": null,
  "livemode": false,
  "maximum_amount": null,
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": null,
  "reference1": null,
  "reference2": null,
  "return_url": null,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": null,
  "variant": null
}

Imports an external mandate into LotusPay for further use, such as for creating a subscription or creating a payment. Supply the unique mandate reference number, the sponsor bank ID and the NACH utility code. LotusPay assumes that the imported mandate is in active status for the purpose of subsequent actions.

ARGUMENTS

Argument Description
creditor_agent_mmbid REQUIRED The 4-character NACH bank code of the sponsor bank of the mandate. An active NACH profile with this sponsor bank must be in place with the given NACH utility code.
nach_utility_code REQUIRED The 18-character NACH utility code of the creditor of the mandate. An active NACH profile with this utility code must be in place with the given sponsor bank.
umrn REQUIRED The 20-character NACH unique mandate reference number of the mandate. Must be a valid UMRN from the NPCI Mandate Management System.

Returns Returns a mandate object if valid arguments were provided. The imported mandate will be in active status.

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 (known as the destination 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 NPCI API mandate variant of NACH 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_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 physical mandates, 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_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_api": false
}

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

ARGUMENTS

Argument Description
nach_bank REQUIRED NACH four-digit identifier of the bank to be retrieved.

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 destination banks that support ach_dr (ACH Debit, physical mandates) or variant_api (NPCI API 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 funds 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, 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 determine 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 calendar month or one month period.

ARGUMENTS

Argument Description
amount REQUIRED Amount in paisa (one hundredths of a Rupee). Must be less than or equal to the mandate's maximum_amount or equal to the mandate's fixed_amount. Validated for internal mandates.
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. Must be on or after the mandate’s first_collection_date and on or before the mandate's final_collection_date (validated for internal mandates). 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
payment 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}/cancel

Example Request

$ curl https://api-test.lotuspay.com/v1/payments/PM004433221AA/cancel \
   -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
payment 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
settlement 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. After the mandate is created, you can then create a subscription. If existing customer or bank_account objects are passed, source uses them, else source automatically creates new ones.

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

The overall flow for eMandates is:

  1. You create a source with fully pre-filled NACH Debit parameters. LotusPay returns a mandate with an authorisation link in url, along with a customer.
  2. Your customer visits the link and gets redirected to their bank's website, where they must complete mandate authorisation via netbanking login or debit card and PIN. See our Knowledge Base at https://support.lotuspay.com for screenshots and more information regarding the customer's experience. 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 via your webhook that the customer has authorised the mandate. You may wish to create a payment, ach_debit or subscription at this point.

If you want LotusPay to send the url link to your customer, you can include an email address in the 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 you have built your own custom payment page approved by LotusPay, the customer will not see the LotusPay mandate view page - they will go directly into the mandate authorisation redirect flow. Contact LotusPay Support for more information.

LotusPay populates the return_url with the following GET parameters when returning your customer to your website:

e.g. ?mandate_id=MD0011AABBCC22&livemode=false&client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3

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.

Your integration needs to use webhooks to be notified of status changes on Mandate and Payment objects.

Once the customer has authorised the mandate, the mandate's status transitions to submitted and it can be used to make a payment request. This transition happens asynchronously and may occur after the customer was redirected back to your website.

Some customers using NACH Debit assume that the order process is complete once they have authorised the mandate and received confirmation from their bank. This results in customers who close their browser instead of following the redirect and returning to your app or website. For these reasons it is essential that your integration rely on webhooks to determine when the mandate becomes chargeable in order to create a payment. Please refer to our webhooks guide for more details.

For physical mandates, LotusPay creates a pre-filled PDF in the standard NPCI format and emails this to you and your customer (you can also download it from the mandate page on the LotusPay dashboard), which your customer must sign and send to you for uploading in the dashboard. Although mandate processing can be initiated basis a scan image, NPCI regulations require the creditor or sponsor bank to be holding the original paper mandate, and different sponsor banks have different operational processes.

The source object

Example Response

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": "savings",
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "ICIC0000047",
    "last4": "5678"
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

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.
client_secret string The client secret of the source. Serves as a password for the mandate URL page. Is also used to confirm that the customer who completed the redirect flow is the same one who entered it.
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.
owner hash Information about the owner of the payment instrument. See child attributes in table below.
redirect hash Information related to the redirect flow. See child attributes in table below.
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.
customer string Identifier of the customer.
mandate string Identifier of the mandate.

Child attributes for nach_debit:

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.
category_code string Four-digit NPCI code of the mandate category e.g. U099. See support article on mandate category codes for more information.
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.
final_collection_date date Final collection date (expiry date) of the mandate. Null entry means "Until Cancelled".
first_collection_date date First collection date (start date) of the mandate.
frequency string The frequency with which debit transaction instructions will be created and processed. Value can be ADHO (ad hoc or as and when presented), INDA (intraday), DAIL (daily), WEEK (weekly), MNTH (monthly), BIMN (bi-monthly), QURT (quarterly), MIAN (half-yearly), YEAR (yearly).
ifsc string Branch IFSC code.
last4 string Last four digits of the bank account number.
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.
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.
variant string The variant of the mandate, either physical or emandate.

Child attributes for owner:

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

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

Create a source

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

Example Request 1 - eMandate for new customer

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[account_holder_name]="A JAIN" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[first_collection_date]="2018-12-18" \
    -d nach_debit[frequency]="MNTH" \
    -d nach_debit[ifsc]="YESB" \
    -d nach_debit[maximum_amount]=10000 \
    -d owner[email]="test@lotuspay.com"\
    -d redirect[return_url]="https://www.lotuspay.com/"
{
    "type": "nach_debit",
    "nach_debit": {
        "account_holder_name": "A JAIN",
        "account_number": "12345678",
        "first_collection_date": "2018-12-18",
        "frequency": "MNTH",
        "ifsc": "YESB",
        "maximum_amount": 10000
    },
    "owner": {
        "email": "test@lotuspay.com"
    },
    "redirect": {
        "return_url": "https://www.lotuspay.com/"
    }
}

Example Response 1 - eMandate for new customer

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": null,
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "YESB",
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": "test@lotuspay.com",
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

Example Request 2 - eMandate for existing customer, new bank account

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[account_holder_name]="A JAIN" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[first_collection_date]="2018-12-18" \
    -d nach_debit[frequency]="MNTH" \
    -d nach_debit[ifsc]="YESB" \
    -d nach_debit[maximum_amount]=10000 \
    -d redirect[return_url]="https://www.lotuspay.com/" \
    -d customer="CU0011AABBCC22"
{
    "type": "nach_debit",
    "nach_debit": {
        "account_holder_name": "A JAIN",
        "account_number": "12345678",
        "first_collection_date": "2018-12-18",
        "frequency": "MNTH",
        "ifsc": "YESB",
        "maximum_amount": 10000
    },
    "redirect": {
        "return_url": "https://www.lotuspay.com/"
    },
    "customer": "CU0011AABBCC22"
}

Example Response 2 - eMandate for existing customer, new bank account

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": null,
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "YESB",
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

Example Request 3 - eMandate for existing bank account

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

Example Response 3 - eMandate for existing bank account

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": null,
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "YESB",
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

Example Request 4 - eMandate on bank account token

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

Example Response 4 - eMandate on bank account token

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": null,
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "YESB",
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

Example Request 5 - Physical mandate

$ curl https://api-test.lotuspay.com/v1/sources \
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -d type="nach_debit" \
    -d nach_debit[account_holder_name]="A JAIN" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[account_type]="savings" \
    -d nach_debit[first_collection_date]="2018-12-18" \
    -d nach_debit[frequency]="MNTH" \
    -d nach_debit[ifsc]="ICIC0000047" \
    -d nach_debit[maximum_amount]=10000 \
    -d nach_debit[variant]="physical" \
    -d owner[email]="test@lotuspay.com" \
{
    "type": "nach_debit",
    "nach_debit": {
        "account_holder_name": "A JAIN",
        "account_number": "12345678",
        "account_type": "savings",
        "first_collection_date": "2018-12-18",
        "frequency": "MNTH",
        "ifsc": "ICIC0000047",
        "maximum_amount": 10000,
        "variant": "physical"
    },
    "owner": {
        "email": "test@lotuspay.com"
    }
}

Example Response 5 - Physical mandate

{
  "id": "SC004433221AA",
  "object": "source",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": "savings",
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": "ICIC0000047",
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": "physical"
  },
  "owner": {
    "email": "test@lotuspay.com",
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

Creates a new source object.

ARGUMENTS

Argument Description
type REQUIRED The type of the source to create. Value is nach_debit.
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_debit REQUIRED Information for the mandate to be created by the source object. See child arguments in the table below.
owner optional dictionary Information about the owner of the payment instrument. See child arguments in 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.
bank_account optional The unique identifier of the existing bank_account on which to create the mandate, or a bank account token. LotusPay will expand this into the full bank account details and link the mandate to the customer who owns this bank account. If you give bank_account you should not give account_holder_name, account_number, account_type, or ifsc, and vice versa.
customer optional The unique identifier of the customer on which to create the mandate. LotusPay will expand this into the full customer details and link the mandate to this customer. If you give customer you should not give owner and vice versa.

Child arguments for nach_debit:

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 optional Customer's bank account type. One of savings, current, nre, nro, or cc. Required only for physical mandates.
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. RESTRICTED to Pro merchants.
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 be given (one or the other, not both). If variant is emandate then collection_amount can be up to 10000000 (10 million paisa = 1 lakh rupees). If variant is physical, then collection_amount can be up to 1000000000 (1 billion paisa = 1 crore rupees).
final_collection_date optional, default is null Final collection date (expiry date) of the mandate. Null entry means "Until Cancelled".
first_collection_date REQUIRED First collection date (start date) of the mandate.
frequency optional The frequency with which debit transaction instructions are to be created and processed. Value can be ADHO (ad hoc or as and when presented), MNTH (monthly), QURT (quarterly), MIAN (half-yearly) or YEAR (yearly) for all mandate types, and also INDA (intraday), DAIL (daily), WEEK (weekly) or BIMN (bi-monthly) for eMandate variants. Required for physical mandates.
ifsc REQUIRED Customer's bank identifier. For physical mandates, must be a valid 11-digit IFSC code in the correct format. For eMandates, must be a valid 4-digit destination bank identifier e.g. HDFC. Letters must be capitalised.
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 be given (one or the other, not both). It is strongly recommended to use maximum_amount as it offers more flexibility than collection_amount. If variant is emandate then maximum_amount can be up to 10000000 (10 million paisa = 1 lakh rupees). If variant is physical, then maximum_amount can be up to 1000000000 (1 billion paisa = 1 crore rupees).
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 active 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. 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 active 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. 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. Not applicable for eMandates.
variant optional, default is emandate The variant of the mandate to be created, either physical or emandate. RESTRICTED to Pro merchants activated for physical mandates.

Child arguments for owner:

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

Child arguments for redirect:

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

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",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "created": 1530224170,
  "flow": "redirect",
  "livemode": true,
  "metadata": {
  },
  "nach_debit": {
    "account_holder_name": "A JAIN",
    "account_type": "savings",
    "category_code": null,
    "maximum_amount": 10000,
    "final_collection_date": null,
    "first_collection_date": "2018-12-18",
    "frequency": "MNTH",
    "ifsc": null,
    "last4": "5678",
    "maximum_amount": null,
    "nach_sponsor_bank": null,
    "nach_utility_code": null,
    "reference1": null,
    "variant": null
  },
  "owner": {
    "email": null,
    "mobile": null,
    "name": null,
    "pan": null,
    "phone": null
  },
  "redirect": {
    "return_url": "https://www.lotuspay.com/",
    "url": "https://test.lotuspay.com/pay/AL00AABBCCDDEE?client_secret=src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3"
  },
  "type": "nach_debit",
  "customer": "CU0011AABBCC22",
  "mandate": "MD0011AABBCC22",
}

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 specified mandate is crediting to merchant's bank account, the subscription creates ACH debits. If the NACH profile of the specified mandate is creditng to LotusPay, the subscription creates payments. If the NACH profile of the specified mandate 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": 10000,
  "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-12-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.
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 amount=10000 \
   -d count=2 \
   -d day_of_month=23 \
   -d interval="month" \
   -d mandate="MD0011DD22RR33" \
   -d name="Order 123" \
   -d start_date="2018-12-02"
{
    "amount": 10000,
    "count": 2,
    "day_of_month": 23,
    "interval": "month",
    "mandate": "MD0011DD22RR33",
    "name": "Order 123",
    "start_date": "2018-12-02"
}

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 10000,
  "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-12-02",
  "status": "active",
}

Creates a subscription on an existing mandate (internal or external).

ARGUMENTS

Argument Description
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. Should be less than or equal to mandate's maximum_amount (validated for internal mandates). Must be less than or equal to Rs 1 crore (1 billion paisa).
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 should be on or before the mandate's final_collection_date (validated for internal mandates).
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 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 should fall between mandate's first_collection_date and final_collection_date (validated for internal mandates).
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 (validated for internal mandates).
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 not belong to any plan. Mandate's NACH profile must have a creditor bank account. Internal mandate's frequency must be ADHO. Internal mandate should have maximum_amount, not collection_amount.
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 (validated for internal mandates). When blank, this will be set as today or the internal 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": 10000,
  "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-12-02",
  "status": "active"
}

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

ARGUMENTS

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

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

Update a subscription

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

Example Request

$ curl https://api-test.lotuspay.com/v1/subscriptions/SB004433221AA \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
   -d amount=50000 \
   -d name="Order 321" \
{
    "amount": 50000,
    "name": "Order 321",
}

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 50000,
  "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 321",
  "plan": null,
  "start_date": "2018-12-02",
  "status": "active",
}

Updates an existing independent subscription to match the specified parameters.

ARGUMENTS

Argument Description
id REQUIRED The identifier of the subscription to update. Must not be a plan subscription.
amount optional The amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Should be less than or equal to mandate's maximum_amount (validated for internal mandates). Must be less than or equal to Rs 1 crore (1 billion paisa).
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.
name optional The name of the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

Returns Returns an updated subscription object.

Cancel a subscription

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

Example Request

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

Example Response

{
  "id": "SB004433221AA",
  "object": "subscription",
  "amount": 10000,
  "cancelled_at": "2018-12-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-12-02",
  "status": "cancelled"
}

Cancels an existing subscription object. Supply the unique subscription identifier. Has no effect on the status of the mandate.

ARGUMENTS

Argument Description
subscription REQUIRED The identifier of the subscription to be cancelled.

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 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 1 - Full bank account details

$ 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 1

{
    "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"
}

Example Request 2 - Partial bank account details

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

Example Response 2

{
    "id": "btok_MhIZEAGfQsxqYPGvm2bSn3mX",
    "object": "token",
    "bank_account": {
        "account_holder_name": "AMIT JAIN",
        "ifsc": "ICIC",
        "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 bank account details with the Source API method.

ARGUMENTS

Argument Description
bank_account optional A dictioinary containing the details of 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 optional Customer's bank account type. One of savings, current, nre, nro, or cc. Required for physical mandates.
ifsc REQUIRED Customer's bank identifier or branch IFSC code. For eMandates, must be a valid 4-digit bank identifier e.g. ICIC. For physical mandates, must be a valid 11-digit branch 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 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.