API - Purchase

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>

 

 

 


Rating: