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/extradata +
- /v1/extradata/{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
+Type: invalid_request_error
+
+ Type: api_error
+
+ 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. | +
Reports
++This reports resource allows you to run and receive output from pre-defined Mifos X reports. A "Generic Resultset" containing Column Heading as well as Data information is returned and JSON is the default output format. However, you can export to CSV format by simply adding "&exportCSV=true" to the end of your URI. +
++Pentaho reports can also be run from this resource. The 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. +
+ + +Parameters
+Note: the prefix R_ below stands for Reporting
+-
+
- R_Name +
- mandatory +
- Report Name. One of the standard or user-defined Mifos X reports. +
- R_'parameter names' ... +
- optional, No defaults +
- The number and names of the parameters depend on the specific report and how it has been configured. FR_officeId is an example parameter name. +
- R_parameterType +
- optional, The only valid value is 'true'. If any other value is provided the parameter will be ignored +
- Determines whether the request looks for reports or paraters that have been configured. +
- exportCSV +
- optional, The only valid value is 'true'. If any other value is provided the parameter 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?FR_officeId=1 +
+ +GET https://thedomainname/v1/reports
+ {
+ "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. + + +
- 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. + + +
- 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 + + +
+
+
+ - + 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. + + +
- 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. + + +
- 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
+ },
+ {...},
+ {...}
+ ]
+}
+
+