Purchase
This API can be used to register a purchase action. Purchase will mostly result in enrollment in the item being purchased. The API is a restrictive one and can be called by an admin of the site only. Any other user trying to invoke this API would result in an error being returned by the API.
API Details
Signature of API call
connection.invokeApi(String uri, String realUserName, Map<String, String> requestParameters);
See details about invoking API in general
Parameter 1 - URI
paymentTxnService.do
Parameter 2 - UserName
Username of any site administrator
Parameter 3 - Request Parameters
Name | Value |
dispatch | purchase |
No other parameters are required | |
userId | userId of user for whom the purchase is made |
openId | openId of user for whom the purchase is made |
userName |
username of user for whom the purchase is made (userId, openId or userName is mandatory) |
entityType |
type of item to purchase, can be one of following - COURSE_SESSION - PROGRAM_SESSION |
entityId | id of item |
extId |
external id of item (id or external id is mandatory) |
groupPayment | true or false (optional), indicates whether the purchase is for the same user or is for other users (group purchase) |
numUsers | number of users for which to purchase (optional... mandatory in case of group purchase) |
authCodeId |
coupon id if redeeming a coupon - To prevent same coupon being used more than once for same user for the same programSession / courseSession set site property PREVENT_COUPON_REUSE=true in Site Details->Customization |
orderDate | optional - specifies order date (if not current date) |
payTxnId | optional - payment transaction reference (order id of external system) |
payTxnRef | optional - additional payment reference note |
All date parameters are numbers, represented as epoch time in milliseconds - number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT),
Inactive user note - If the user account is inactive for which the purchase is being made, then by default API will return error. If you like to allow inactive users to make purchase and get auto activated as a result of the purchase, then enable this security option Site Admin->Site Details->Security->Allow inactive users to login and check their certificates, purchase from catalog
Response
1. Response on successfully getting results
HTTP Response Code = HttpServletResponse.SC_OK
Response XML
returns invoice id (used as order id within EduBrite lms)
<response code="0">
<msgs>
<msg>
<code>0</code>
<value>
<![CDATA[ Success ]]>
</value>
</msg>
</msgs>
<data>
<invoice id="13469c1a-a98f-11e7-b7b8-743cce595392"></invoice>
</data>
</response>
Response for successful group purchase. Returns invoice id and coupon code id i.e. auth code id
<response code="0">
<msgs>
<msg>
<code>0</code>
<value>
<![CDATA[ Success ]]>
</value>
</msg>
</msgs>
<data>
<invoice id="d1b62124-a990-11e7-b7b8-743cce595392">
<authCode id="e36ff976-a990-11e7-b7b8-743cce595392" />
</invoice>
</data>
</response>
2. Response for unauthorized access
HTTP Response Code = HttpServletResponse.SC_UNAUTHORIZED
Response XML
<response code="-1">
<msgs>
<msg>
<code>0005</code>
<value><![CDATA[You are not allowed to perform this action.]]></value>
</msg>
</msgs>
</response>
Error response when user not found
<response code="-1">
<msgs>
<msg>
<code>0004</code>
<value>
<![CDATA[
Unable to find User with matching UserId=null, OpenId=null, UserName=ajackson.
]]>
</value>
</msg>
</msgs>
</response>
Error response when item not found
<response code="-1">
<msgs>
<msg>
<code>0004</code>
<value>
<![CDATA[
Unable to find ProgramSession with matching ID=2b4fbd7e-90ca-11e7-8677-2ef1301af376, ExtId=null.
]]>
</value>
</msg>
</msgs>
</response>
Error response when auth code (coupon) is not found
<response code="0">
<msgs>
<msg>
<code>0004</code>
<value>
<![CDATA[
Unable to find AuthCode with matching ID=36ff976-a990-11e7-b7b8-743cce595392.
]]>
</value>
</msg>
</msgs>
</response>
Error response when user account is inactive and inactive users are not allowed to login and purchase. Site Details->Security-> Allow inactive users to login and check their certificates, purchase from catalog is not checked
<response code="-1">
<msgs>
<msg>
<code>0002</code>
<value><![CDATA[Account is inactive. ]]></value>
</msg>
</msgs>
</response>
Code Snippet
/* Check API Call for detail generic code */
Map<String, String> parameters = new HashMap<String, String>();
parameters.put("dispatch", "purchase");
String retStr = connection.invokeApi("paymentTxnService.do", "chenry", parameters);
System.out.println(retStr);
Example of group purchase
Map<String, String> parameters = new HashMap<String, String>();
parameters.put("dispatch", "purchase");
parameters.put("entityType", "PROGRAM_SESSION");
parameters.put("extId", "xxx-xxx-xxx");
parameters.put("groupPayment", "true");
parameters.put("numUsers", "3");
parameters.put("userName", "jdoe"); //user name of the team lead who is purchasing for his/her team
String retStr = connection.invokeApi("paymentTxnService.do", "chenry", parameters);
Response will contain the auth code id of the newly generated coupon.
Once you have the coupon code, you can make use of it for enrolling the team members
Map<String, String> parameters = new HashMap<String, String>();
parameters.put("dispatch", "purchase");
parameters.put("entityType", "PROGRAM_SESSION");
parameters.put("extId", "xxx-xxx-xxx");
parameters.put("authCodeId", "xxx-xxx-xxx-xxx"); //auth code id from previous call
parameters.put("userName", "user1"); //user name of the team member to enroll
String retStr = connection.invokeApi("paymentTxnService.do", "chenry", parameters);
purchase call doesn't check if same user has already purchased before. If user was already enrolled then their end date will get incremented as per the reenrollment mechanism which will advance the user's end date by adding maxSubscriptionDays to greater of <current date or user's previous end date>
API Documentation
Examples
- User Creation
- User Update
- User List
- Get User Details
- Add User to Group(s)
- Remove User from Group(s)
- User Activate
- User Deactivate
- User Login
- Group List
- Group Membership
- Course Subscription(Coupon Code)
- Subscribed Events List
- Non Subscribed Events List
- Test Instances in Microsite
- Forum APIs
- Javascript Example
Client Example
Quick Links
- Home
- Getting Started
- Knowledgebase
- Video Tutorials
- Google Apps Integration
- Gilly (Plugin for Atlassian Confluence)