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. If you request your API key, we will respond within one working day. We will grant your production environment API key only after you have finished testing in the test environment. 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.

Testing the API

You can use Postman or similar software to use the API in the Test or Production environments. Here is a Collection of Test endpoints that you can download and import into Postman to get started quickly. It contains one Request for each of the endpoints in the LotusPay API. In Postman, right-click on the Collection, select Edit, select Authorization, enter your API key as the username, then click on Update. Then you're good to go!

Cursor Pagination

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

Example Request

$ curl https://api-test.lotuspay.com/v1/nach_banks?limit=3&page=1 \
   -u sk_test_XjIHowXWSI23uvjepz2X82: \
URL-encoded arguments.

Example Response

{
    "object": "list",
    "url": "/v1/nach_banks",
    "has_more": true,
    "data": [
        {
            "id": "AACX",
            "name": "AKHAND ANAND CO.OP BANK LTD.",
            "display_name": "Akhand Anand Co-operative Bank Ltd."
        },
        {
            "id": "ABCX",
            "name": "THE AURANGABAD DISTRICT CENTRAL COOP BANK LIMITED",
            "display_name": "The Aurangabad District Central Co-operative Bank Ltd."
        },
        {
            "id": "ABDX",
            "name": "DR. AMBEDKAR NAGRIK SAHAKARI BANK MYDT GWALIOR",
            "display_name": "Dr. Ambedkar Nagrik Sahakari Bank Mydt Gwalior"
        }
    ]
}

All top-level API resources (except Source) have support for bulk fetches via "list" API methods. For instance, you can list mandates, list customers, and list payments. These list API methods share a common structure, taking at least these two parameters: limit and page.

LotusPay utilises cursor-based pagination via the page number parameter. This parameter takes an existing object ID value (see below) and return objects in reverse chronological order.

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.
page optonal The page number to return.

LIST RESPONSE FORMAT

Attribute Description
object string, value is "list" A string describing the object type returned.
data array An array containing the actual response elements, paginated by any request parameters.
has_more boolean Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
url string The URL for accessing this list.

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

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

// Sample code in PHP

<?php

// webhook_payload => {serialized_response: <encrypted_json_string>}
$str = <encrypted_json_string>;
$key = <webhook_encyrption_key>;

$iv = substr($str, 0, 16);
$encry_data = substr($str, 16);
$decry_data = openssl_decrypt($encry_data, "AES-128-CBC", $key, 0, $iv);
print_r($decry_data);

// parse json string to obj
$obj = json_decode($decry_data);
print_r($obj);

?>
// Sample code in Node.js

const crypto = require('crypto');
// webhook_payload => {serialized_response: <encrypted_json_string>}
const str = <encrypted_json_string>;
const key = <webhook_encyrption_key>;

const algorithm = 'aes-128-cbc';
try {
    const iv = str.substring(0,16);
    const encry_data = str.substring(16, ) ;
    const decipher = crypto.createDecipheriv(algorithm, key, iv);
    decipher.setAutoPadding(true);
    let decry_data = decipher.update(encry_data, 'base64', 'utf8');
    decry_data += decipher.final('utf8');
    console.log(decry_data);

    // parse json string to obj
    let event_obj = JSON.parse(decry_data);
    console.log(event_obj);
}
catch(err) { }
// Sample code in Ruby


require 'base64'
require 'securerandom'
require 'openssl'

# webhook_payload => {serialized_response: <encrypted_json_string>}
str = <encrypted_json_string>
key = <webhook_encyrption_key>

iv = str[0..15]
encry_data = Base64.decode64(str[16..-1])
decipher = OpenSSL::Cipher::AES.new(128, :CBC)
decipher.decrypt
decipher.key = key
decipher.iv = iv
decry_data = decipher.update(encry_data) + decipher.final

# parse json string to obj
event_obj = JSON.parse(decry_data)
// Sample code in Java
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

public class WebHookDecrpyt
{   
    public static void main(String[] args) throws Exception
    {   
        // webhook_payload => {serialized_response: <encrypted_json_string>}
        String encr_data = <encrypted_json_string>;
        String key = <webhook_encyrption_key>;
        byte[] iv = encr_data.substring(0, 16).getBytes();
        System.out.println("String : "+ encr_data.substring(16));
        byte[] cipher_text = Base64.getMimeDecoder().decode(encr_data.substring(16).getBytes("UTF-8"));
        byte[] byte_key = key.getBytes();
        SecretKey secret_key = new SecretKeySpec(byte_key, 0, byte_key.length, "AES"); 
        String decr_data = decrypt(cipher_text, secret_key, iv);
        System.out.println("DeCrypted Text : "+ decr_data);
    }

    public static String decrypt (byte[] cipherText, SecretKey key,byte[] IV) throws Exception
    {
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        SecretKeySpec keySpec = new SecretKeySpec(key.getEncoded(), "AES");
        IvParameterSpec ivSpec = new IvParameterSpec(IV);
        cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);
        byte[] decryptedText = cipher.doFinal(cipherText);
        return new String(decryptedText);
    }
}

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.

Webhook data is encrypted using the AES 128 algorithm. To decrypt the data, you will need to use your webhook key, which you can find in your LotusPay dashboard.

Here is sample code for decrypting the webhook post.

Steps for testing in Java:

  1. Save the sample code as WebHookDecrypt.java
  2. Replace the contents of and as per specification, and save the file.
  3. Compile using javac WebHookDecrypt.java.
  4. If compilation succeeds, run using java WebHookDecrypt.
  5. You should see the decrypted event data in your console.

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 API can only be used on mandates for which LotusPay is not processing payments. This means mandates for which you are receiving direct credit, and LotusPay is not receiving your funds. If LotusPay is the initial creditor of your funds before paying out to you, you should use the Payments API instead.

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",
  "sequence_number": "6858307575",
  "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.
sequence_number string NPCI-allotted transaction sequence number. Present only if status is confirmed or failed.
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",
  "sequence_number": "6858307575",
  "status": "confirmed",
  "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",
  "sequence_number": "6858307575",
  "status": "confirmed",
  "umrn": "HDFC000012345678"
}

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

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",
  "sequence_number": "6858307575",
  "status": "cancelled",
  "umrn": "HDFC000012345678"
}

Cancels an existing ACH debit object. Supply the unique ACH debit identifier. 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, 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 ACH debits for the mandate specified by this identifier. If you pass this argument, you cannot also pass customer, subscription or umrn.
subscription optional Only return ACH debits for the subscription specified by this identifier. If you pass this argument, you cannot also pass customer, mandate 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, mandate or subscription.

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.

ACH Debit Collections

ach_debit_collection objects represent a group of ach_debit objects. Each ACH debit collection contains the funds collected from one or many ach_debit objects in a day. ACH debit collections are created automatically after an ACH debit has been successfully collected. The API allows you to retrieve your ACH debit collections. You can retrieve individual ACH debit collections as well as a list of all of your ACH debit collections.

The ACH Debit Collections API can only be used on mandates for which LotusPay is not processing payments. This means mandates for which you are receiving direct credit, and LotusPay is not receiving your funds. If LotusPay is the initial creditor of your funds before paying out to you, you should use the Settlements API instead.

The ACH debit collection object

Example Response

{
  "id": "DO0011DD2211AA",
  "object": "ach_debit_collection",
  "amount": 2212300,
  "arrival_date": "2018-03-24",
  "created": 1530224170,
  "destination": "BA00CC33221AA",
  "livemode": false
}

ATTRIBUTES

Attribute Description
id string Unique identifier for the object.
object string, value is "ach_debit_collection" 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 ACH debit collection 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.

Retrieve an ACH debit collection

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

Example Request

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

Example Response

{
  "id": "DO0011DD2211AA",
  "object": "ach_debit_collection",
  "amount": 2212300,
  "arrival_date": "2018-03-24",
  "created": 1530224170,
  "destination": "BA00CC33221AA",
  "livemode": false
}

Retrieves an existing ACH debit collection object. Supply the unique ACH debit collection identifier.

ARGUMENTS

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

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

List all ACH debit collections

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

Example Request

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

Example Response

{
  "object": "list",
  "url": "/v1/ach_debit_collections",
  "has_more": false,
  "data": [
        {
            "id": "DO004433221AA"
        },
        {
            "id": "DO004433221BB"
        },
        {
            "id": "DO004433221CC"
        },
        {...
        }
  ]
}

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

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 ACH debit collections. Each entry in the array is a separate ACH debit collection object. If no more ACH debit collections 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 and mandate objects. The API allows you to retrieve your bank accounts. You can retrieve individual bank accounts as well as a list of all of a customer's bank accounts.

The bank account object

Example Response

{
  "id": "BA004433221AA",
  "object": "bank_account",
  "created": 1530224170,
  "account_ifsc": "ICIC0000047",
  "account_holder_name": "Amit Jain",
  "account_last4": "1234",
  "account_type": "savings",
  "bank_name": "ICICI BANK",
  "customer": "CU004433221AA",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [

    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/bank_accounts/BA004433221AA/mandates"
    },
  "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_ifsc string Branch IFSC code.
account_last4 string Last four digits of the bank account number.
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. ICICI BANK).
customer string Identifier of the customer who owns the bank account.
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.
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/ach_debits. 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:
   -d account_holder_name="Amit Jain" \
   -d account_ifsc="ICIC0000047" \
   -d account_number="12341234" \
   -d account_type="savings"

{
    "account_holder_name": "Amit Jain",
    "account_ifsc": "ICIC0000047"
    "account_number": "12341234",
    "account_type": "savings",
}

Example Response

{
  "id": "BA004433221AA",
  "object": "bank_account",
  "created": 1530224170,
  "account_holder_name": "Amit Jain",
  "account_ifsc": "ICIC0000047",
  "account_last4": "1234",
  "account_type": "savings",
  "bank_name": "ICICI BANK",
  "customer": "CU004433221AA",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [

    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/bank_account/BA004433221AA/mandates"
    },
  "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_ifsc REQUIRED Customer's bank branch 11-digit IFSC code.
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.

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_ifsc": "ICIC0000047",
  "account_last4": "1234",
  "account_type": "savings",
  "bank_name": "ICICI BANK",
  "customer": "CU004433221AA",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [

    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/bank_account/BA004433221AA/mandates"
    },
  "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 identifier.

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 ach_debit, bank_account, mandate, payment and subscription 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",
  "identification": "ABCDE1234A",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
        {
            "id": "MD0011223366A"
        },
        {
            "id": "MD00123459DDA"
        }
    ],
    "total_count": 2,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "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.
identification string Customer's identification number e.g. Permanent Account Number (tax ID in India).
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.
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",
  "identification": "ABCDE1234A",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
    ],
    "total_count": 0,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "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.
id optional Customer's identification number e.g. Permanent Account Number (tax ID in India).
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's mobile number.
name optional Customer's name. Can be different to their bank account name.
phone optional Customer's phone.

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",
  "identification": "ABCDE1234A",
  "livemode": false,
  "mandates": {
    "object": "list",
    "data": [
        {
            "id": "MD0011223366A"
        },
        {
            "id": "MD00123459DDA"
        }
    ],
    "total_count": 2,
    "url": "/v1/customers/CU004433221AA/mandates"
    }
  "metadata": {
  },
  "mobile": "9123456789",
  "name": "Amit Jain",
  "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.
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. ach_debit objects and 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_bank_code": "ICIC",
  "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",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "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_identification": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "date_submitted": "2018-06-10",
  "debtor_agent": "ICICI BANK",
  "debtor_agent_mmbid": "ICIC0000001",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "is_external": false,
  "livemode": false,
  "mandate_request_id": "MD004433221AA",
  "maximum_amount": null,
  "message_id": "MD004433221AA",
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "onmags_response": nil,
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "status": "active",
  "subscription": null,
  "umrn": "ICIC7000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate_api"
}

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_bank_code string NACH bank code of the customer's bank.
account_holder_name string Name in the customer's 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.
client_secret string The client secret of the mandate. Serves as a password for the mandate URL page for eMandate variants. Is also used to confirm that the customer who completed the redirect flow is the same one who entered it. The same value is stored in source.
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_identification string Identifier number of the customer, such as PAN number or merchant's customer reference number.
customer_phone string Phone number of the customer.
date_acknowledged date For physical and emandate_esign variants, date on which the mandate was acknowledged by NPCI - the UMRN was generated. For emandate_api variant, date on which the sponsor bank responded.
date_amended date Date on which the mandate was amended.
date_cancelled date Date on which the mandate was cancelled.
date_responded date For physical and emandate_esign variants, date on which the destination bank responded. For emandate_api variant, date on which the sponsor bank responded.
date_submitted date Date that the mandate was submitted/authorised.
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.
is_external boolean Has the value true if the mandate was originally created in LotusPay or the value false if the mandate was originally created externally and then imported to LotusPay.
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_request_id string The mandate request ID of the MMS CREATE INPUT. For variant emandate_api, mandate_request_id is the NPCI ONMAGS transaction reference, populated when the customer returns from ONMAGS.
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.
message_id string The message ID of the MMS CREATE INPUT.
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.
onmags_response string For variant emandate_api, the responseXML from NPCI ONMAGS in JSON format, populated when the customer returns from ONMAGS.
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 mandate.
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, emandate_api or emandate_esign.

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_bank_code": "ICIC",
  "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",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "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_identification": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "date_submitted": "2018-06-10",
  "debtor_agent": "ICICI BANK",
  "debtor_agent_mmbid": "ICIC0000001",
  "failure_reason": null,
  "first_collection_date": "2018-06-18",
  "final_collection_date": "2018-08-18",
  "frequency": "ADHO",
  "is_external": false,
  "livemode": false,
  "mandate_request_id": "MD004433221AA",
  "maximum_amount": null,
  "message_id": "MD004433221AA",
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "onmags_response": nil,
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "status": "active",
  "subscription": null,
  "umrn": "ICIC7000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate_api"
}

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

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_bank_code": "ICIC",
  "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",
  "client_secret": "src_client_secret_DUeNTTEBn6QG5mU27pQxyQj3",
  "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_identification": "AABBC1234B",
  "customer_phone": "9999123456",
  "date_acknowledged": "2018-06-15",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2018-06-17",
  "date_submitted": "2018-06-10",
  "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",
  "is_external": false,
  "livemode": false,
  "mandate_request_id": "MD004433221AA",
  "maximum_amount": null,
  "message_id": "MD004433221AA",
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "onmags_response": nil,
  "reference1": "MERCHANTREF1",
  "reference2": "MD004433221AA",
  "return_url": "https://www.lotuspay.com/",
  "status": "active",
  "subscription": null,
  "umrn": "ICIC7000000000272000",
  "url": "https://test.lotuspay.com/pay/AL00652J9UYX3D",
  "variant": "emandate_api"
}

Cancels an existing mandate. Supply the unique LotusPay mandate identifier 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). To cancel an external mandate, first you must import it.

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.
umrn optional The NACH Unique Mandate Reference Number of the mandate to be cancelled. For internal mandates, umrn is not present until the mandate has reached acknowledged status. Either id or umrn must be supplied.

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

Import an external mandate

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

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/import \
    -u sk_test_XjIHowXWSI23uvjepz2X82 \
    -d account_holder_name="A JAIN" \
    -d account_number="12341234" \
    -d account_type="savings" \
    -d category_code="L001" \
    -d creditor_agent_mmbid="HDFC0999999" \
    -d date_acknowledged="2019-01-01" \
    -d date_responded="2019-01-05" \
    -d date_submitted="2019-01-01" \
    -d debtor_agent_mmbid="HSBC0400002" \
    -d first_collection_date="2019-01-01" \
    -d frequency="ADHO" \
    -d mandate_request_id="ABC123" \
    -d message_id="DEF456" \
    -d nach_utility_code="NACH00000000001111" \
    -d umrn="HSBC6000000000272000" \
{
    "account_holder_name": "A JAIN",
    "account_number": "12341234",
    "account_type": "savings",
    "category_code": "L001",
    "collection_amount": 10000,
    "creditor_agent_mmbid": "HDFC0999999",
    "date_acknowledged": "2019-01-01",
    "date_responded": "2019-01-05",
    "date_submitted": "2019-01-01",
    "debtor_agent_mmbid": "HSBC0400002",
    "first_collection_date": "2019-01-01",
    "frequency": "ADHO",
    "mandate_request_id": "ABC123",
    "message_id": "DEF456",
    "nach_utility_code": "NACH00000000001111",
    "umrn": "HSBC6000000000272000"
}

Example Response

{
  "id": "MD004433221AA",
  "object": "mandate",
  "account_bank_code": null,
  "account_holder_name": "A JAIN",
  "account_last4": "1234",
  "account_type": "savings",
  "amend_status": null,
  "bank_account": "BA004433DD55AA",
  "cancel_status": null,
  "cancel_reason": null,
  "category_code": "L001",
  "client_secret": null,
  "collection_amount": 10000,
  "created": 1530224170,
  "creditor": "LOTUSPAY SOLUTIONS PVT LTD",
  "creditor_agent": "HFDC BANK",
  "creditor_agent_mmbid": "HDFC0999999",
  "customer": "CU00443311DDAA",
  "customer_email": null,
  "customer_mobile": null,
  "customer_name": null,
  "customer_identification": null,
  "customer_phone": null,
  "date_acknowledged": "2019-01-01",
  "date_amended": null,
  "date_cancelled": null,
  "date_responded": "2019-01-05",
  "date_submitted": "2019-01-01",
  "debtor_agent": "HSBC",
  "debtor_agent_mmbid": "HSBC0400002",
  "failure_reason": null,
  "first_collection_date": "2019-01-01",
  "final_collection_date": null,
  "frequency": "ADHO",
  "is_external": true,
  "livemode": false,
  "mandate_request_id": "ABC123",
  "maximum_amount": "DEF456",
  "message_id": "MD004433221AA",
  "metadata": {
  },
  "nach_utility_code": "NACH00000000001111",
  "occurrence_sequence_type": "RCUR",
  "onmags_response": nil,
  "reference1": null,
  "reference2": null,
  "return_url": null,
  "status": "active",
  "subscription": null,
  "umrn": "HSBC6000000000272000",
  "url": null,
  "variant": "emandate_esign"
}

RESTRICTED to Pro merchants

Imports an external mandate into LotusPay for further use, such as for cancelling the mandate or creating a subscription, payment or ACH debit. You must provide accurate mandate details sourced directly from your sponsor bank's database. LotusPay treats the imported mandate as active for the purpose of subsequent actions.

ARGUMENTS

Argument Description
account_holder_name REQUIRED Name in the customer's bank account.
account_number REQUIRED Customer's bank account number. Must be at least five characters in length.
account_type REQUIRED Type of account. One of savings, current, nre, nro, cc or other.
category_code REQUIRED The industry classification code of the mandate. See Support article on mandate category codes.
collection_amount optional Collection amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Either collection_amount or maximum_amount must be supplied.
creditor_agent_mmbid REQUIRED The 11-character NACH bank code of the sponsor bank of the mandate. Letters must be capitalised. An active NACH profile with this sponsor bank must be in place with the given NACH utility code.
customer_email optional Email address of the customer. Must be supplied if the original mandate contains the value.
customer_mobile optional Mobile number of the customer. Must be supplied if the original mandate contains the value.
customer_identification optional Identifier number of the customer, such as PAN number or merchant's customer reference number. Must be supplied if the original mandate contains the value.
customer_phone optional Phone number of the customer. Must be supplied if the original mandate contains the value.
date_acknowledged REQUIRED Date that the mandate was acknowledged.
date_responded REQUIRED Date that the mandate was responded to.
date_submitted REQUIRED Date that the mandate was submitted/authorised.
debtor_agent_mmbid REQUIRED The 11-character branch IFSC code of the customer's bank account. Letters must be capitalised.
first_collection_date REQUIRED The first collection date (start date) of the mandate.
final_collection_date optional The final collection date (end date) of the mandate. Must be nil if mandate continues until cancelled. Must be supplied if the original mandate contains the value.
frequency optional The frequency of the mandate. Value can be ADHO, INDA,DAIL, WEEK, MNTH, BIMN, QURT, MIAN, YEAR. See mandate frequencies support article for more information. Must be supplied if the original mandate contains the value.
mandate_request_id REQUIRED The mandate request ID of the mandate.
maximum_amount optional Maximum amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Either collection_amount or maximum_amount must be supplied.
message_id REQUIRED The message ID of the mandate.
metadata optional Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
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.
reference1 optional Reference 1 value of the mandate. Must be supplied if the original mandate contains the value.
reference2 optional Reference 2 value of the mandate. Must be supplied if the original mandate contains the value.
umrn REQUIRED The 20-character NACH unique mandate reference number of the mandate. Must be a valid UMRN from the NPCI Mandate Management System. Must be unique across the LotusPay 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. You can also filter for status and variant. You can use any combination of these arguments.

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 A filter on the status of the mandates to be returned e.g. status=pending.
variant optional A filter on the variant of the mandates to be returned e.g. variant=physical.

Returns A dictionary with a data property that contains an array of up to limit mandates. 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 identifier 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 the initial creditor of funds before paying out to you. If you're receiving direct credit of funds, you should use the ACH Debits API instead.

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": 10000,
    "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 identifier.

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 identifier. 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
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.
umrn optional Only return payments for the umrn specified by this identifier.

Returns A dictionary with a data property that contains an array of up to limit payments. Passing an optional mandate or umrn 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.

Physical Mandate Images

physical_mandate_image objects represent the JPG images (scan or photo) of physical NACH mandates. A physical mandate image is attached to a mandate. The API allows you to upload your physical mandate images and check their details. You can overwrite an existing physical mandate image for a pending mandate by simply uploading a replacement in its place for the same mandate ID.

The physical mandate image object

Example Response

{
  "object": "physical_mandate_image",
  "created": 1530224170,
  "livemode": false,
  "mandate": "MD004433221AA",
  "updated": 1530224170
}

ATTRIBUTES

Attribute Description
object string, value is "mandate" 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.
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 ID of the mandate to which this physical mandate image belongs.
updated timestamp Time at which the object was updated. Measured in seconds since the Unix epoch.

Upload a physical mandate image

POST https://api-test.lotuspay.com/v1/mandates/[ID]/physical_mandate_image

Example Request

$ curl https://api-test.lotuspay.com/v1/mandates/MD004433221AA/physical_mandate_image\
    -u sk_test_XjIHowXWSI23uvjepz2X82: \
    -F file="C:\Users\User\Documents\file.jpg" \
{
    "file": "C:\Users\User\Documents\file.jpg"
}

Example Response

{
  "object": "physical_mandate_image",
  "created": 1530224170,
  "livemode": false,
  "mandate": "MD004433221AA",
  "updated": 1530224170
}

Uploads a physical mandate image. To upload a file to LotusPay, you’ll need to send a request of type multipart/form-data. The request should contain the file you would like to upload, as well as the parameters for creating a file.

ARGUMENTS

Argument Description
mandate REQUIRED The identifier of the mandate to which the physical mandate image is to be attached. Mandate's status must be pending, and variant must be physical. Mandate identifier goes in the query string.
file REQUIRED A file to upload. The file should follow the specifications of RFC 2388 (which defines file transfers for the multipart/form-data protocol). File must be format JPG, and file size no greater than 300kb. These attributes are validated. The following attributes are required by LotusPay, but not validated in the API: Image colour scheme should be black and white or greyscale. Image dimension aspect ratio should be 24:11. Image should be of physical mandate scan, legible and in good light. Image should be cropped around the border of the mandate. If the image does not meet these specifications, the mandate will be returned from pending_submission to pending for you to upload a corrected image.

Returns Returns a physical mandate image object if a valid mandate identifier and file were provided.

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 Settlements API can only be used on mandates for which LotusPay is processing payments. This means mandates for which LotusPay is the initial creditor of funds before paying out to you. If you're receiving direct credit of funds, you should use the ACH Debit Collections API instead.

The settlement object

Example Response

{
  "id": "SM0011DD2211AA",
  "object": "settlement",
  "amount": 2212300,
  "arrival_date": "2018-03-24",
  "created": 1530224170,
  "destination": "BA00CC33221AA",
  "livemode": false,
  "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.
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,
  "method": "instant",
  "status": "settled"
}

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

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 of the ONMAGS response by sending an event POST request to your webhook url, containing the full GET Mandate payload which includes the onmags_response payload and the mandate status. If the mandate authorisation has failed for any reason, the mandate remains in pending status so that the customer can retry with the same link. If the customer has successfully authorised the mandate, the mandate moves from pending status to submitted status and the authorisation link becomes blocked from further attempts. You may also use the GET Mandate API to get the full mandate payload, including its status. See the Knowledge Base article on mandate statuses for more information. 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 via email, 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.

If you want LotusPay to send the url link to your customer via SMS, you can include their mobile number in the mobile argument, and a short link will instantly be sent to that mobile number (in live mode only).

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.

If you have built your own custom payment page certified 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, payment and ACH debit objects.

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

If the NACH ONMAGS system gives a failure message when the customer attempts eMandate authorisation, the mandate will remain in pending status. You can use the Mandate API to see the ONMAGS response in the onmags_response key. If you are using a redirect flow approach, you can decide whether to send the customer back to ONMAGS (using the same link) to reattempt authorisation. If you are independently sending links to customers, the customer can anyway revisit the link and reattempt authorisation. The link expires only after successful authorisation, or if you withdraw the mandate.

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 us, and therafter 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 or ACH debit. 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 your customer (you can also download it from the mandate page on the LotusPay dashboard). You can use this pre-filled PDF or you can use a hand-written blank mandate. Your customer must sign and submit the mandate to you for uploading in the dashboard. Refer to the Support Knowledge Base for more information on physical mandates.

Visit https://support.lotuspay.com to learn more about mandate statuses, processing timelines and failures.

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_bank_code": "ICIC",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": null,
    "identification": null,
    "mobile": null,
    "name": 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 for eMandate variants. Is also used to confirm that the customer who completed the redirect flow is the same one who entered it. The same value is stored in mandate.
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_bank_code string Four-character NACH bank code of the customer's bank. Note: This may not be the first four characters of the branch IFSC.
account_holder_name string Name of the customer that owns the bank account.
account_ifsc string Branch IFSC code of the customer's bank.
account_last4 string Last four digits of the customer's bank account number.
account_type string Type of account. This is savings, current, nre, nro, cc or other.
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 transactions can be submitted. Value can be ADHO (ad hoc, or as and when presented), MNTH (monthly), QURT (quarterly), MIAN (half-yearly) or YEAR (yearly) for all mandate variants, and also INDA (intraday), DAIL (daily), WEEK (weekly) or BIMN (bi-monthly) for eMandate variant.
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 identifier. Appears in physical mandates. Nil for eMandates.
reference2 string Merchant's own identifier. Appears in physical mandates. Nil for eMandates.
variant string The variant of the mandate, either physical or emandate.

Child attributes for owner:

Attribute Description
email string Customer's email address.
identification string Customer's identification number e.g. Permanent Account Number (tax ID in India).
mobile string Customer's mobile number.
name string Customer's name.
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 authorised their mandate.
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_bank_code]="YESB" \
    -d nach_debit[account_holder_name]="A JAIN" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[frequency]="ADHO" \
    -d nach_debit[maximum_amount]=10000 \
{
    "type": "nach_debit",
    "nach_debit": {
        "account_bank_code": "YESB",
        "account_holder_name": "A JAIN",
        "account_number": "12345678",
        "frequency": "ADHO",
        "maximum_amount": 10000
    }
}

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_bank_code": "YESB",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "ADHO",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": "null",
    "identification": null,
    "mobile": null,
    "name": null,
    "phone": null
  },
  "redirect": {
    "return_url": null,
    "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_bank_code]="YESB" \
    -d nach_debit[account_holder_name]="A JAIN" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[first_collection_date]="2019-01-01" \
    -d nach_debit[frequency]="MNTH" \
    -d nach_debit[maximum_amount]=10000 \
    -d redirect[return_url]="https://www.lotuspay.com/" \
    -d customer="CU0011AABBCC22"
{
    "type": "nach_debit",
    "nach_debit": {
        "account_bank_code": "YESB",
        "account_holder_name": "A JAIN",
        "account_number": "12345678",
        "first_collection_date": "2019-01-01",
        "frequency": "MNTH",
        "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_bank_code": "YESB",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": null,
    "identification": null,
    "mobile": null,
    "name": "AMIT JAIN",
    "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]="2019-01-01" \
    -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": "2019-01-01",
        "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_bank_code": "YESB",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": null,
    "identification": null,
    "mobile": null,
    "name": "AMIT JAIN",
    "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]="2019-01-01" \
    -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": "2019-01-01",
        "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_bank_code": "YESB",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": null,
    "identification": null,
    "mobile": null,
    "name": 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_ifsc]="ICIC0000047" \
    -d nach_debit[account_number]="12345678" \
    -d nach_debit[account_type]="savings" \
    -d nach_debit[first_collection_date]="2019-01-01" \
    -d nach_debit[frequency]="MNTH" \
    -d nach_debit[maximum_amount]=10000 \
    -d nach_debit[reference1]="LOAN_ID_123" \
    -d nach_debit[variant]="physical" \
    -d owner[email]="test@lotuspay.com" \
    -d owner[mobile]="9123456789"
{
    "type": "nach_debit",
    "nach_debit": {
        "account_holder_name": "A JAIN",
        "account_ifsc": "ICIC0000047",
        "account_number": "12345678",
        "account_type": "savings",
        "first_collection_date": "2019-01-01",
        "frequency": "MNTH",
        "maximum_amount": 10000,
        "reference1": "LOAN_ID_123",
        "variant": "physical"
    },
    "owner": {
        "email": "test@lotuspay.com",
        "mobile": "9123456789"
    }
}

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_bank_code": null,
    "account_holder_name": "A JAIN",
    "account_last4": "5678",
    "account_type": "savings",
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": "LOAN_ID_123",
    "reference2": null,
    "variant": "physical"
  },
  "owner": {
    "email": "test@lotuspay.com",
    "identification": null,
    "mobile": "9123456789",
    "name": 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. Source metadata is replicated to Mandate metadata.
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 optional dictionary Parameters required for the redirect flow. Required for eMandates. 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_ifsc, account_number or account_type 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_bank_code optional The four-digit NACH bank code of the customer's bank. Note: This is generally the first four characters of the branch IFSC, but there are exceptions e.g. Ujjivan Small Finance Bank has IFSC codes beginning UJVN but its NACH bank code is USFB. Required for eMandates. Not permitted for physical mandates. See the NACH Banks endpoint for more details.
account_holder_name REQUIRED The name of the person or business that owns the bank account. Must match the bank's records.
account_ifsc optional Customer's bank branch identifier. Must be a valid 11-digit IFSC code in the correct format. Letters must be capitalised. Required for physical mandates. Not permitted for eMandates.
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, cc or other. Required for physical mandates. Not permitted for eMandates.
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 *optional, default is tomorrow's date` First collection date (start date) of the mandate.
frequency optional, default value is null The frequency with which debit transactions can be submitted. 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. Null value creates mandate with occurrence_sequence_type of OOFF (one-off mandate), else RCUR (recurring mandate).
maximum_amount optional Maximum amount of the mandate. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1. Required if collection_amount is not given. Either maximum_amount or collection_amount can 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 identifier 1. Appears in physical mandate. Not permitted for eMandates.
reference2 optional, default is the id of the mandate that will be created by the source Merchant's own identifier 2. Appears in physical mandate. Not permitted for eMandates.
variant optional, default is emandate The variant of the mandate to be created, either physical or emandate. RESTRICTED to Pro merchants that are activated for physical mandates.

Child arguments for owner:

Argument Description
email optional Customer's email address. Appears in physical mandate. Does not appear in eMandate. If present, email invitation will be sent to the customer.
identification optional Customer's identification number e.g. Permanent Account Number (tax ID in India). For physical mandate variant, identification is stored in the mandate details but does not appear on the paper mandate. Does not appear in the eMandate.
mobile optional Customer's mobile number. Appears in physical mandate. Does not appear in eMandate. India mobile numbers must be 10 digits long and begin with 6, 7, 8 or 9.
name optional Customer's name. Can be different to bank account name. If no value is given then value is copied from the account_holder_name in nach_debit. Does not appear in the mandate.
phone optional Customer's phone number. For physical mandate variant, phone is stored in the mandate details but does not appear on the paper mandate. Does not appear in the eMandate.

Child arguments for redirect:

Argument Description
return_url optional Required for eMandates. The URL you provide to redirect the customer back to you after they authenticated their mandate. 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_bank_code": "ICIC",
    "account_holder_name": "A JAIN",
    "account_ifsc": null,
    "account_last4": "5678",
    "account_type": null,
    "category_code": "U099",
    "collection_amount": null,
    "final_collection_date": null,
    "first_collection_date": "2019-01-01",
    "frequency": "MNTH",
    "maximum_amount": 10000,
    "nach_sponsor_bank": "HDFC",
    "nach_utility_code": "NACH90000000006000",
    "reference1": null,
    "reference2": null,
    "variant": "emandate"
  },
  "owner": {
    "email": null,
    "identification": null,
    "mobile": null,
    "name": 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:

Subscription statuses follow these rules:

  1. If the mandate is in pending status, the subscription will begin in pending_customer_approval status and will automatically change status if the mandate changes status.
  2. If the mandate is in pending_submission, submitted, acknowledged or active status, the subscription will begin in active status.
  3. A pending_customer_approval subscription will automaticallly move to active status if its pending mandate moves to pending_submission or submitted status.
  4. A pending_customer_approval subscription will automatically move to cancelled status if its pending mandate moves to withdrawn status.
  5. An active subscription will automatically move to cancelled status if its mandate moves to failed, cancelled or expired status.
  6. An active subscription will automatically move to finished status once its last charge date (if any) has passed.
  7. Cancelling an active subscription has no effect on its mandate.

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 or equal to mandate's collection_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.
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. Must match the day_of_month, if any.

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. Must be in pending_customer_approval or active status.
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 or equal to mandate's collection_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.

MOBILE SDK

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

After you integrate the SDK, the overall flow is:

  1. You use the LotusPay API or dashboard to generate a mandate/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 secure client check-out style experience for the user to authorise a mandate. For you to know the outcome of the mandate authorisation 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/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/plan link inserted in the code.

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

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/mandate authorisation link, then click continue.

Simple test app