Mifos X API Documentation

Much of the presentation ideas here have been taken from the very good API reference (https://stripe.com/docs/api)

The Mifox X API is organized around REST. Our API is designed to have predictable, resource-oriented URLs, to use HTTP response codes to indicate API errors, and to use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

API Endpoint

https://thedomainname/

Summary of Resource URL Patterns

/v1/offices
/v1/offices/template
/v1/offices/{OFFICEID}
/v1/loanproducts
/v1/loanproducts/template
/v1/loanproducts/{PRODUCTID}
/v1/configurations
/v1/configurations/currency

/v1/reports
/v1/reports/{REPORTNAME}
/v1/additionalfields
/v1/additionalfields/{datasetType}/{datasetName}/{datasetPKValue}

Authentication

JPW: Keith, this needs to change to whatever is right after authentication has been added. Don't know if you will go with keys or passwords (I assume passwords)... but can you fix it so we have one user or one user per role that doesn't need a password or always has a password of 'password' so we can let ppl do stuff from the browser and/or REST plugins? We can talk about this.

STRIPE content: You authenticate to the Mifos X API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

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

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl https://api.stripe.com/v1/charges \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

JPW: We'll update this after... curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). A sample test API key has been provided in all the examples on the page, so you can test out any example right away.

Errors

JPW:Need to update this Stripe uses conventional HTTP response codes to indicate 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 resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g. a card is declined), we return a 402 error code.

All errors return JSON with a type (one of card_error, invalid_request_error, or api_error) and message describing the particular problem.

Attributes

type: The type of error returned (card_error, invalid_request_error, api_error) Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason. Invalid request errors arise when your request has invalid parameters. API errors cover any other type of problem (e.g. a temporary problem with Stripe's servers) and should turn up only very infrequently.
message: A user-friendly message describing the error
code: optional; For card errors, additional information about the user-friendly message to display for this error (e.g. "Your card was declined.")
param: optional; The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP Status Code Summary

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Stripe's end.

Errors

Invalid Request Errors Type: invalid_request_error API Errors Type: api_error Card Errors Type: card_error

Code	Details
invalid_number	The card number is invalid
incorrect_number	The card number is incorrect
invalid_expiry_month	The card's expiration month is invalid
invalid_expiry_year	The card's expiration year is invalid
invalid_cvc	The card's security code is invalid
expired_card	The card has expired
invalid_amount	An invalid amount was entered
incorrect_cvc	The card's security code is incorrect
card_declined	The card was declined.
missing	There is no card on a customer that is being charged.
duplicate_transaction	A transaction with identical amount and credit card information was submitted very recently.
processing_error	An error occurred while processing the card.

Additional Fields

In Mifos X, any number of "Sets" of "Additional Fields" can be configured for a Mifos X database table ("Type").

For example, portfolio_client is the database table that holds client data. Typically, MFI's want more client related fields than is provided by Mifos X out-of-the-box. The MFI might add a Set called "Additional Info" containing some fields that are typically input when creating a client. They might then add another Set called "Highly Improbable Info" containing some fields that are only input in exceptional circumstances.

The additional fields resource allows you to retrieve and update any Additional Fields data that has been configured in Mifos X.

The Mifos X Individual Lending client application uses a JQuery plugin called stretchydata which, itself, uses this additional fields resource to provide a pretty flexible additional fields User Interface (UI). Put a link to an example here.

List Additional Fields Sets

Lists the Sets of additional fields have been defined in Mifos X.

Arguments

type: optional; The Additional Field Type (Mifos X database table) to restrict the output to

Example Request: http://localhost:8080/mifosng-provider/api/v1/additionalfields?type=portfolio_client

GET https://thedomainname/v1/additionalfields

{
  "additionalFieldsSets": [
    {
      "id": 1,
      "name": "Additional Information",
      "type": "portfolio_client"
    },
    {
      "id": 9,
      "name": "Highly Improbable Info",
      "type": "portfolio_client"
    }
  ]
}

Retrieve Additional Data

Runs a report and returns the report output.

Arguments

R_'parameter names' ...: optional, No defaults; The number and names of the parameters depend on the specific report and how it has been configured. R_officeId is an example parameter name.; Note: the prefix R_ stands for Reporting
parameterType: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Determines whether the request looks in the list of reports or the list of parameters for its data.
exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON. Doesn't apply to Pentaho reports.

Example Request: http://localhost:8080/mifosng-provider/api/v1/reports/Client%20Listing?R_officeId=1

GET https://thedomainname/v1/reports/{REPORTNAME}

{
  "columnHeaders": [
    {
      "columnName": "Office/Branch",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Name",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Joining Date",
      "columnType": "DATE",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    }
  ],
  "data": [
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Patrick",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Dennis",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "Smith, John",
        "2009-01-11"
      ]
    },
... more "row" entries
  ]
}

Update Additional Data

Runs a report and returns the report output.

Arguments

R_'parameter names' ...: optional, No defaults; The number and names of the parameters depend on the specific report and how it has been configured. R_officeId is an example parameter name.; Note: the prefix R_ stands for Reporting
parameterType: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Determines whether the request looks in the list of reports or the list of parameters for its data.
exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON. Doesn't apply to Pentaho reports.

Example Request: http://localhost:8080/mifosng-provider/api/v1/reports/Client%20Listing?R_officeId=1

GET https://thedomainname/v1/reports/{REPORTNAME}

{
  "columnHeaders": [
    {
      "columnName": "Office/Branch",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Name",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Joining Date",
      "columnType": "DATE",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    }
  ],
  "data": [
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Patrick",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Dennis",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "Smith, John",
        "2009-01-11"
      ]
    },
... more "row" entries
  ]
}

Reports

The reports resource allows you to run and receive output from pre-defined Mifos X reports. The default output is a JSON formatted "Generic Resultset". The Generic Resultset contains Column Heading as well as Data information. However, you can export to CSV format by simply adding "&exportCSV=true" to the end of your URI.

If Pentaho reports have been pre-defined, they can also be run through this resource. Pentaho reports can return HTML, PDF or CSV formats.

Add examples showing links to client listing report producing json, then csv, then a pentaho report producing html, pdf, csv

The Mifos X Individual Lending client application uses a JQuery plugin called stretchyreporting which, itself, uses this reports resource to provide a pretty flexible reporting User Interface (UI). Put a link to an example here.

List Reports

Lists all reports and their parameters. If a report has more than one parameter it will be listed the same number of times as it has parameters.

Arguments

exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON.

Example Request: http://localhost:8080/mifosng-provider/api/v1/reports

GET https://thedomainname/v1/reports

{
  "columnHeaders": [
    {
      "columnName": "report_id",
      "columnType": "INT",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "report_name",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "report_type",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
... more "columnHeaders" entries
  ],
  "data": [
    {
      "row": [
        "29",
        "Client Listing",
        "Table",
        null,
        null,
        "5",
        null,
        "selectOfficeId"
      ]
    },
    {
      "row": [
        "42",
        "Client Listing - Additional and Unlikely",
        "Table",
        null,
        null,
        "5",
        null,
        "selectOfficeId"
      ]
    },
    {
      "row": [
        "30",
        "Client Loans Listing",
        "Table",
        null,
        null,
        "5",
        null,
        "selectOfficeId"
      ]
    },
... more "Row" entries
  ]
}

Running a Report

Runs a report and returns the report output.

Arguments

R_'parameter names' ...: optional, No defaults; The number and names of the parameters depend on the specific report and how it has been configured. R_officeId is an example parameter name.; Note: the prefix R_ stands for Reporting
parameterType: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Determines whether the request looks in the list of reports or the list of parameters for its data.
exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON. Doesn't apply to Pentaho reports.

Example Request: http://localhost:8080/mifosng-provider/api/v1/reports/Client%20Listing?R_officeId=1

GET https://thedomainname/v1/reports/{REPORTNAME}

{
  "columnHeaders": [
    {
      "columnName": "Office/Branch",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Name",
      "columnType": "VARCHAR",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    },
    {
      "columnName": "Joining Date",
      "columnType": "DATE",
      "columnLength": null,
      "columnDisplayType": null,
      "columnValues": []
    }
  ],
  "data": [
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Patrick",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "O'Meara, Dennis",
        "2009-01-04"
      ]
    },
    {
      "row": [
        "Demo MFI Head Office",
        "Smith, John",
        "2009-01-11"
      ]
    },
... more "row" entries
  ]
}

Creating a New Customer

Creates a new customer object.

Arguments

card

optional, default is null

A card to attach to the customer. The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details, with the options described below. Whenever you attach a card to a customer, Stripe will automatically validate the card. A customer with a card can be used when creating a charge or put on a recurring billing plan.

number: required; The card number, as a string without any separators.
exp_month: required; Two digit number representing the card's expiration month.
exp_year: required; Four digit number representing the card's expiration year.
cvc: optional, highly recommended; Card security code
name: optional; Cardholder's full name.
address_line1: optional
address_line2: optional
address_zip: optional
address_state: optional
address_country: optional

coupon

optional, default is null

If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount. You can manage your coupons in the coupon section of your account.

email

optional, default is null

The customer's email address. It is displayed alongside the customer in the web interface and can be useful for searching and tracking.

description

optional, default is null

An arbitrary string which you can attach to a customer object. It is displayed alongside the customer in the web interface.

plan

optional, default is null

The identifier of the plan to subscribe the customer to. If provided, the returned customer object has a 'subscription' attribute describing the state of the customer's subscription.

trial_end

optional, default is null

UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to.

Returns

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and cards, if that information has been provided. If a non-free plan is specified and a card is not provided (unless the plan has a trial period), the call will return an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will return an error.

If a card has been attached to the customer, the returned customer object will have an active_card attribute containing the card's details.

POST https://api.stripe.com/v1/customers

curl https://api.stripe.com/v1/customers \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -d "description=Customer for site@stripe.com" \
   -d "card[number]=4242424242424242" \
   -d "card[exp_month]=5" \
   -d "card[exp_year]=2013"

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "You must supply a valid card"
  }
}

Retrieving a Customer

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

Like with a charge, you can view the retrieved customer directly in your browser.

https://vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE@api.stripe.com/v1/customers/ch_I7HoyUbJDACuPe

Arguments

id: required; The identifier of the customer to be retrieved.

Returns

Returns a customer object if a valid identifier was provided. When requesting the ID of a customer that has been deleted, a subset of the customer's information will be returned, including a "deleted" property, which will be true.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

Updating a Customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the card parameter, that becomes the customer's active card which will be used for all charges in future.

This request accepts mostly the same arguments as the customer creation call. However, subscription-related arguments (plan and trial_end) are not accepted. To change those, one must update the customer's subscription directly.

Arguments

card

optional, default is null

A new card to attach to the customer. The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details, with the options described below. A customer with a card can be used when creating a charge or put on a recurring billing plan. Although not all information is required, the extra info helps prevent fraud.

number: required; The card number, as a string without any separators.
exp_month: required; Two digit number representing the card's expiration month.
exp_year: required; Four digit number representing the card's expiration year.
cvc: optional, highly recommended; Card security code
name: optional; Cardholder's full name.
address_line1: optional
address_line2: optional
address_zip: optional
address_state: optional
address_country: optional

coupon

optional, default is null

If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount. You can manage your coupons in the coupon section of your account.

description

optional, default is null

An arbitrary string which you can attach to a customer object. It is displayed alongside the charge in the web interface. It's often a good idea to use an email address as a description for tracking later.

email

optional

The customer's email address. It is displayed alongside the customer in the web interface and can be useful for searching and tracking.

Returns

Returns the customer object if the update succeeded. Errors will be thrown if update parameters are invalid. For example, specifying an invalid coupon or an invalid card will return an error.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -d "description=Customer for site@stripe.com"

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": "Customer for site@stripe.com",
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

Deleting a Customer

Permanently deletes a customer. It cannot be undone.

Arguments

id: required; The identifier of the customer to be deleted.

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, an error is returned.

Unlike other objects, deleted customers can still be retrieved through the API, in order to be able to track the history of customers while still removing their credit card details and preventing any further operations to be performed (such as adding a new subscription).

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -X DELETE

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

List all Customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recently created customers appearing first.

Like with an individual customer, you can view the list of customers directly in your browser.

https://vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE@api.stripe.com/v1/customers

Arguments

count: optional, default is 10; A limit on the number of customers to be returned. Count can range between 1 and 100 customers.
offset: optional, default is 0; An offset into your customer array. The API will return the requested number of customers starting at that offset.

Returns

A dictionary with a data property that contains an array of up to count customers, starting at index offset. 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.

GET https://api.stripe.com/v1/customers

curl https://api.stripe.com/v1/customers \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

{
  data: [
    {
    "discount": {
      "end": 1339507966,
      "start": 1336829566,
      "object": "discount",
      "customer": "cus_QEvO1l6xtJNbTI",
      "id": "di_Ogh2mPRH0Y200d",
      "coupon": {
        "times_redeemed": 1,
        "duration_in_months": null,
        "livemode": false,
        "redeem_by": null,
        "object": "coupon",
        "duration": "once",
        "percent_off": 10,
        "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
        "max_redemptions": null
      }
    },
    "livemode": false,
    "delinquent": false,
    "object": "customer",
    "email": null,
    "subscription": null,
    "account_balance": 0,
    "description": null,
    "id": "cus_QEvO1l6xtJNbTI",
    "active_card": null,
    "created": 1336829566
  },
    {...},
    {...}
  ]
}

Customers

Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object

Attributes

id

string

object

string, value is "customer"

livemode

boolean

created

timestamp

account_balance

integer or null

Current balance, if any, being stored on the customer's account. If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice.

active_card

hash

Hash describing the current card on the customer, if there is one.

object: string
exp_month: integer
exp_year: integer
fingerprint: string; Uniquely identifies this particular card number. You can use this attribute to check whether two customers who've signed up with you are using the same card number, for example.
last4: string
type: string; Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown
address_country: string or null; Billing address country, if provided when creating card
address_line1: string or null
address_line1_check: string or null; If address_line1 was provided, results of the check: pass, fail, or unchecked
address_line2: string or null
address_state: string or null
address_zip: string or null
address_zip_check: string or null; If address_zip was provided, results of the check: pass, fail, or unchecked
country: string or null; Two-letter ISO code representing the country of the card (as accurately as we can determine it). You could use this attribute to get a sense of the international breakdown of cards you've collected.
cvc_check: string or null; If a CVC was provided, results of the check: pass, fail, or unchecked
name: string or null; Cardholder name

or null

delinquent

boolean or null

Whether or not the latest charge for the customer's latest invoice has failed

description

string or null

discount

hash, discount object or null

Describes the current discount active on the customer, if there is one.

email

string or null

subscription

hash, subscription object or null

Hash describing the current subscription on the customer, if there is one. If the customer has no current subscription, this will be null.

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

Creating a New Customer

Creates a new customer object.

Arguments

card

optional, default is null

A card to attach to the customer. The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details, with the options described below. Whenever you attach a card to a customer, Stripe will automatically validate the card. A customer with a card can be used when creating a charge or put on a recurring billing plan.

number: required; The card number, as a string without any separators.
exp_month: required; Two digit number representing the card's expiration month.
exp_year: required; Four digit number representing the card's expiration year.
cvc: optional, highly recommended; Card security code
name: optional; Cardholder's full name.
address_line1: optional
address_line2: optional
address_zip: optional
address_state: optional
address_country: optional

coupon

optional, default is null

If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount. You can manage your coupons in the coupon section of your account.

email

optional, default is null

The customer's email address. It is displayed alongside the customer in the web interface and can be useful for searching and tracking.

description

optional, default is null

An arbitrary string which you can attach to a customer object. It is displayed alongside the customer in the web interface.

plan

optional, default is null

The identifier of the plan to subscribe the customer to. If provided, the returned customer object has a 'subscription' attribute describing the state of the customer's subscription.

trial_end

optional, default is null

UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to.

Returns

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and cards, if that information has been provided. If a non-free plan is specified and a card is not provided (unless the plan has a trial period), the call will return an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will return an error.

If a card has been attached to the customer, the returned customer object will have an active_card attribute containing the card's details.

POST https://api.stripe.com/v1/customers

curl https://api.stripe.com/v1/customers \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -d "description=Customer for site@stripe.com" \
   -d "card[number]=4242424242424242" \
   -d "card[exp_month]=5" \
   -d "card[exp_year]=2013"

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "You must supply a valid card"
  }
}

Retrieving a Customer

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

Like with a charge, you can view the retrieved customer directly in your browser.

https://vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE@api.stripe.com/v1/customers/ch_I7HoyUbJDACuPe

Arguments

id: required; The identifier of the customer to be retrieved.

Returns

Returns a customer object if a valid identifier was provided. When requesting the ID of a customer that has been deleted, a subset of the customer's information will be returned, including a "deleted" property, which will be true.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

Updating a Customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the card parameter, that becomes the customer's active card which will be used for all charges in future.

This request accepts mostly the same arguments as the customer creation call. However, subscription-related arguments (plan and trial_end) are not accepted. To change those, one must update the customer's subscription directly.

Arguments

card

optional, default is null

A new card to attach to the customer. The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user's credit card details, with the options described below. A customer with a card can be used when creating a charge or put on a recurring billing plan. Although not all information is required, the extra info helps prevent fraud.

number: required; The card number, as a string without any separators.
exp_month: required; Two digit number representing the card's expiration month.
exp_year: required; Four digit number representing the card's expiration year.
cvc: optional, highly recommended; Card security code
name: optional; Cardholder's full name.
address_line1: optional
address_line2: optional
address_zip: optional
address_state: optional
address_country: optional

coupon

optional, default is null

If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount. You can manage your coupons in the coupon section of your account.

description

optional, default is null

An arbitrary string which you can attach to a customer object. It is displayed alongside the charge in the web interface. It's often a good idea to use an email address as a description for tracking later.

email

optional

The customer's email address. It is displayed alongside the customer in the web interface and can be useful for searching and tracking.

Returns

Returns the customer object if the update succeeded. Errors will be thrown if update parameters are invalid. For example, specifying an invalid coupon or an invalid card will return an error.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -d "description=Customer for site@stripe.com"

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": "Customer for site@stripe.com",
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

Deleting a Customer

Permanently deletes a customer. It cannot be undone.

Arguments

id: required; The identifier of the customer to be deleted.

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, an error is returned.

Unlike other objects, deleted customers can still be retrieved through the API, in order to be able to track the history of customers while still removing their credit card details and preventing any further operations to be performed (such as adding a new subscription).

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}

curl https://api.stripe.com/v1/customers/cus_QEvO1l6xtJNbTI \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE: \
   -X DELETE

{
  "discount": {
    "end": 1339507966,
    "start": 1336829566,
    "object": "discount",
    "customer": "cus_QEvO1l6xtJNbTI",
    "id": "di_Ogh2mPRH0Y200d",
    "coupon": {
      "times_redeemed": 1,
      "duration_in_months": null,
      "livemode": false,
      "redeem_by": null,
      "object": "coupon",
      "duration": "once",
      "percent_off": 10,
      "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
      "max_redemptions": null
    }
  },
  "livemode": false,
  "delinquent": false,
  "object": "customer",
  "email": null,
  "subscription": null,
  "account_balance": 0,
  "description": null,
  "id": "cus_QEvO1l6xtJNbTI",
  "active_card": null,
  "created": 1336829566
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_QEvO1l6xtJNbTI"
  }
}

List all Customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recently created customers appearing first.

Like with an individual customer, you can view the list of customers directly in your browser.

https://vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE@api.stripe.com/v1/customers

Arguments

count: optional, default is 10; A limit on the number of customers to be returned. Count can range between 1 and 100 customers.
offset: optional, default is 0; An offset into your customer array. The API will return the requested number of customers starting at that offset.

Returns

A dictionary with a data property that contains an array of up to count customers, starting at index offset. 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.

GET https://api.stripe.com/v1/customers

curl https://api.stripe.com/v1/customers \
   -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

{
  data: [
    {
    "discount": {
      "end": 1339507966,
      "start": 1336829566,
      "object": "discount",
      "customer": "cus_QEvO1l6xtJNbTI",
      "id": "di_Ogh2mPRH0Y200d",
      "coupon": {
        "times_redeemed": 1,
        "duration_in_months": null,
        "livemode": false,
        "redeem_by": null,
        "object": "coupon",
        "duration": "once",
        "percent_off": 10,
        "id": "JAVA-COUPON-fa8e8918-2f9e-4def-9675-ed19d6f4d41b",
        "max_redemptions": null
      }
    },
    "livemode": false,
    "delinquent": false,
    "object": "customer",
    "email": null,
    "subscription": null,
    "account_balance": 0,
    "description": null,
    "id": "cus_QEvO1l6xtJNbTI",
    "active_card": null,
    "created": 1336829566
  },
    {...},
    {...}
  ]
}

Navigation

Full API Docs

General

Reports

Additional Fields

Customers

Mifos X API Documentation

API Endpoint

Summary of Resource URL Patterns

Authentication

Errors

Attributes

HTTP Status Code Summary

Errors

Additional Fields

List Additional Fields Sets

Arguments

Retrieve Additional Data

Arguments

Update Additional Data

Arguments

Reports

List Reports

Arguments

Running a Report

Arguments

Creating a New Customer

Arguments

Returns

Retrieving a Customer

Arguments

Returns

Updating a Customer

Arguments

Returns

Deleting a Customer

Arguments

Returns

List all Customers

Arguments

Returns

Customers

The customer object

Attributes

Creating a New Customer

Arguments

Returns

Retrieving a Customer

Arguments

Returns

Updating a Customer

Arguments

Returns

Deleting a Customer

Arguments

Returns

List all Customers

Arguments

Returns