Payment by credit card AwareIM Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
[<10>]
====== Payment by credit card ======

Another feature that we have initially left out is online payment by members (see [[6000_case_study:0300_library_app#Payments|Requirements]]). We will have a look at how to configure this feature in this section.

In our application members will pay through the PayPal credit card payment system. In order to pay through PayPal one has to have a PayPal account. We will assume that our library has opened such an account. Technically, any system that wants to accept payments by credit card made through PayPal has to call the URL of the PayPal site and pass a number of parameters, such as the name of the account, product quantity, price, product code and URL of the page to return to. The rest is then handled by secure PayPal pages where the customer enters her credit card number and finalizes the purchase. If the purchase is successful PayPal returns to the URL you specified as “success” URL. If the purchase failed PayPal also returns to the URL you specified as “failure” URL.

//**AwareIM**// makes it possible to easily integrate credit card payment into your application. We will show you how to do this in the next sections.

=====  New business objects =====

First of all we need to configure a business object that will represent the PayPal credit card payment system. To do this we define a new business object as usual (see [[6000_case_study:0400_configuration:0500_business_objects_relationships:0200_config_objects]]), enter its name ''PayPal'' and enter one attribute ''Name''((  In principle, PayPal object does not need any attributes. However, AwareIM requires that at least one attribute is defined for a business object. )). Our application will be communicating with the PayPal system, therefore we click on the “Communication” property and //**AwareIM**// displays a number of possible channels that it can communicate with.

The channel that we will be communicating through is called the //URL channel// – see also the [[2000_concepts:0900_prod_feats:0300_comm_with_other_systems|Defining Communication Channels]] section. This channel allows communicating with a software system through URL. We tick the checkbox in the row representing the URL channel we specify the settings of the channel. We enter “https://www.paypal.com/cgi-bin/webscr” as the URL of the service provider – this is the URL of the PayPal page handling the payment. Then we enter “return” as the name of the parameter indicating the URL to return to if a service has been successful. This is the name of the parameter that PayPal expects (among other parameters passed to the PayPal page), which contains the URL that PayPal will return to if payment has been successful. We do not have to worry about the URL itself – this is taken care of automatically by //**AwareIM**//. Similarly we enter the name of the parameter indicating the URL to return to if service fails – ''cancel_return''. We click on the OK button and then we click on the “Save” button to create the PayPal object.

Now we need to define the object that will represent parameters that PayPal expects when its URL is called. PayPal expects the following parameters:

^Parameter^Description^
|''business''|contains the name of the PayPal account|
|''amount''|purchase quantity|
|''item_name''|the name of the item being purchases|
|''item_code''|internal code of the item being purchased|
|''currency_code''|code of the currency|
|''no_shipping''|if value is “1” shipping information is not included|
|''cmd''|code of the PayPal operation. Must be “_xclick” in our case|

We define the new business object called ''PayPalParameters'' with the attributes that have exactly the same names as the parameters above. All attributes can be of the “Plain Text” type. We specify the following initial values for the attributes:

^Attribute^Initial value^
|''Business''|The name of the PayPal account of our library|
|''Amount''|1|
|''item_code''|0010 (can be anything we like)|
|''currency_code''|USD|
|''no_shipping''|1|
|''Cmd''|_xclick|

Once we have defined the PayPalParameters object we need to define the service of the ''PayPal'' object. Intelligent objects can expose services that we can request from rules. We will define such a service for the ''PayPal'' object. We open the ''PayPal'' object for editing and click on the “Communication” property in the list of properties of the object. Then we click on the “Add” button to add a new service. The “Service” dialog is displayed. We enter the name of the service ''PayByCreditCard'' and select the ''PayPalParameters'' object as input for this service. Then we click on the OK button and then save changes to the ''PayPal'' object.

====  Changes to the Payment object ====

When a member will be making payment by credit card our application will be creating an instance of the Payment object, just like it does when the operator [[6000_case_study:0400_configuration:0700_operations:1500_register_payment|registers payment]] of a member . Unlike the registration of payment operation, though, there will be a potentially long period when a member makes a payment through PayPal pages. During this period the Payment object will be in an intermediary state, since we don’t know yet whether the payment will succeed or fail. Therefore we introduce a life cycle for the Payment object – we add the ''Status'' attribute to this object with possible values ''New'' and ''Applied''. The ''Applied'' state is assigned to the object after payment has been completed

<alert type="primary" icon="fa info-circle">
**note**

We can also have the ''Failed'' state which indicates that the payment has failed</alert> 

We modify the ''Payment amount validation'' rule to consider the ''New'' state:

<code aim>IF Payment.Status='New' AND Payment.Amount > Payment.Member.OutstandingCharges THEN 
   REPORT ERROR 'Payment amount cannot exceed outstanding charges.' </code>

Once payment has been made we do not want anyone to change its details, therefore we enter the ''Payment protection'' rule:

<code aim>IF  Payment.Status='Applied' THEN 
   PROTECT Payment FROM ALL EXCEPT System </code>

We also add the action that sets the Payment state to ''Applied'' in the “[[6000_case_study:0400_configuration:0700_operations:1500_register_payment|RegisterPayment]]” process.

=====  Credit card payment operation =====

In our credit card payment operation we will be creating the instance of ''Payment'' object and then use the details of this object to call service of the PayPal object. So we need a process to perform these actions. We define the new ''MakePayment'' process that does not require any input((  We do not need to provide the ''Member'' object as process input since the process will only be used by members and therefore we will use the currently logged in member )) and has the following actions:

<code aim>ENTER NEW Payment WITH Payment.Member=LoggedInMember
 CREATE PayPalParameters WITH 
   PayPalParameters.amount=Payment.Amount, 
   PayPalParameters.item_name=Payment.Description
 REQUEST SERVICE PayByCreditCard OF PayPal USING
   PayPalParameters
   Payment.Status = 'Applied'
 DISPLAY MESSAGE 'Your payment has been successfully processed' </code>

The actions above are quite straightforward. The only point we want to mention here is that we do not create the instance of the PayPal object in the process nor do we need to worry about the PayPal object being in the context. We will create only one instance of the PayPal object and we will do it when the [[6000_case_study:0400_configuration:1000_other_requirements:0300_system_initialisation|system is initialized]], not inside the process. In fact, if we are dealing with an intelligent business object that supports the URL channel only one instance of this object should exist in the system. Consequently, it is not necessary to find this instance to put it in the context – //**AwareIM**// will do it automatically.

Now we can define the ''Pay by credit card'' menu item in the ''Member'' visual perspective. This item will start the ''MakePayment'' process. Our members can now pay by credit card online.