You are here : Resources > How-to Guides
  Register        Login
There are no categories in this blog.
More Info

Actravia is an innovative web based platform for Training and Event organizers. Actravia brings online marketing, registration, enrollment, administration and payment processing into a single online center of operations.


Actravia developed by 3rd i

How to Guides
Jul 6

Written by: howto
7/6/2012 3:03 PM  RssIcon

Actravia comes pre-configured to use the Paypal payment gateway. However there are countless providers out there in every country and we don't have the resources to build interfaces to them all! However we have provided a facility whereby a developer can build an interface to their required gateway and integrate it directly into Actravia and the registration workflow. This article will guide you through the process of doing this.

Note: Most payment gateway providers offer a variety of integration approaches. Some involve a redirect to another site, others have a direct API and still others require the gateway options to be embedded in an iFrame. We have created redirects and direct API gateways. However iFrame should also be possible with our API and we'd be happy to assist anybody any developers who wish to do this. (Note: By the time you read this we may have already done this. Contact support for further information).

Core concepts

We will consider the following areas for building the gateway integration.

  1. Base class & gateway provider compilation
  2. Module Settings
  3. Card Capture Control
  4. Payment Processing
  5. Handling the Response

Base Class & Provider Compilation

First off you will need to create a .net project and add references to the Actravia libraries Thirdi.EventBooking.dll and ThirdI.EventBooking.Common.dll which you will find in the website bin directory where you have installed Actravia. Your project can be built in any .net language but we do recommend C# or vb.net. Set the build directory to output to the website bin directory.

You will need to create a single class in your project and derive it from the abstract class Thirdi.EventBooking.Common.PaymentProvider.

For example:

Namespace ThirdI.PaymentProviders

 

Public Class WorldpayXML

Inherits ThirdI.EventBooking.Common.PaymentProvider

 

This class provides a common interface that you must override to correctly implement the gateway interface and is defined as follows:

Public MustInherit Class PaymentProvider

Inherits EventBookingBase

 

    Public MustOverride Function CheckCustomSettings() As Boolean

Public MustOverride Function RenderCardCaptureControl(ByVal destPlace As PlaceHolder, ByVal validationGroup As String) As Boolean

Public MustOverride Function ProcessTransaction(ByVal screenName As ScreenName, ByVal mainView As ViewEventBooking) As Integer

End Class

 

More about this in the following sections.

Module Settings

There are two aspects to the module settings that will need to be configured. First we will need to configure the module to reference the provider we are creating and secondly we need to add settings to the module so that we can configure the gateway in Dotnetnuke.

First off in the general settings find and check the "Alternate Payment Processor" check box.

This will enable you to enter the library details in the text box. Enter in the form AssemblyName,ClassName as illustrated. Make sure the class name is fully qualified with the namespace etc.

Clicking the configure link will dynamically load the library and calls the "CheckCustomSettings" in the processor class. This function is used to dynamically create custom settings for the module and should return true if successfully created or false if fails. An on-screen message will display whether or not it has been successful. Here is an example of some custom settings that have been created for the Payfast payment gateway.

In order to create these settings for the module you need to programme this in the CheckCustomSettings function. Here is a code snippet that demonstrates how a custom setting is created:

Public Overrides Function CheckCustomSettings() As Boolean

 

 

Dim created As Boolean = False

Dim modController As New DotNetNuke.Entities.Modules.ModuleController

If ActiveSettings("setProp_PAYFAST_MERCHANTID") Is Nothing Then

Dim propName As String = "setProp_PAYFAST_MERCHANTID"

modController.UpdateModuleSetting(Me.ModuleId, propName, "Payfast Merchant ID")

propName = "Payfast Merchant ID"

modController.UpdateModuleSetting(Me.ModuleId, propName, "10000100")

created = True

End If

      

     …

 

The module setting "setProp_..." defines the setting to the custom settings. This setting is in turn given a name which will appear in the custom list and is then defaulted. Return the "created" value to the configure event handler for messaging the success/failure of the setting creation.

Card Capture Control

On the checkout screen of Actravia, a placeholder exists where an ascx control can be dynamically loaded in order to capture card details on the form. Within the payment processor there is an abstract function that must be overridden to render the control. This function can just return "True" if you are going to be redirecting and do not wish to render the control.

There is also a default instance available in the package that you can use as a control called CaptureCreditCard.ascx. This renders on the checkout form as illustrated:

It can of course be customized, and elements can be switched on/off as needed such as CVV/CAVV etc. depending on how the merchant account has been configured to correspond with the module settings.

Here for example, is how we render the control for our Authorize.NET processor.

Public Overrides Function RenderCardCaptureControl(ByVal dest As PlaceHolder, ByVal valGroup As String) As Boolean

Dim lblErrorMsg As Label

Dim CAVV As String = ActiveSettings("AUTHORIZE.NET CAVV Required")

If Not dest.HasControls Then

Try

Dim mycontrol As CaptureCreditCard = LoadControl(ActiveSettings("Credit Card Capture Control"))

mycontrol.ID = "ctlCaptureCreditCard_" + valGroup

CType(mycontrol.FindControl("valMandCCNumber"), RequiredFieldValidator).ValidationGroup = valGroup 
 

CType(mycontrol.FindControl("valRegExCCNumber"), RegularExpressionValidator).ValidationGroup = valGroup

Dim ddlMonth As DropDownList = mycontrol.FindControl("ddlExpiresMonth")

Dim ddlYear As DropDownList = mycontrol.FindControl("ddlExpiresYear")

If CAVV = "YES" Then

CType(mycontrol.FindControl("tdCAVV"), HtmlTableCell).Visible = True

CType(mycontrol.FindControl("txtCCAuthCode"), TextBox).Visible = True

 

End If

lblErrorMsg = mycontrol.FindControl("lblErrorMessage")

'Dim liMth As New ListItem("--Month--", "-1")

Dim liMth As New ListItem("-MM-", "-1")

Dim liYear As New ListItem("-YYYY-", "-1")

ddlMonth.Items.Add(liMth)

ddlYear.Items.Add(liYear)

For n = 1 To 12

Dim li As New ListItem

'li.Text = MonthName(n) + " (" + Right("00" + n.ToString, 2) + ")"

li.Text = Right("00" + n.ToString, 2)

li.Value = Right("00" + n.ToString, 2)

ddlMonth.Items.Add(li)

Next

For n = Now.Year() To Now.Year() + 10

Dim li As New ListItem

li.Text = n.ToString

li.Value = Right(n.ToString, 2)

ddlYear.Items.Add(li)

Next

dest.Controls.Add(mycontrol)

lblErrorMsg.Text = ""

lblErrorMsg.Visible = False

Catch ex As Exception

 

End Try

Return True

Else

Return False

End If

 

End Function

 

The parameters give you a reference to the placeholder destination and to the validation group on the form. The controls on the form then join the validation group for the checkout button. Note this example also pre-supposes you have a module setting "Credit Card Capture Control" which references the control. You can safely hardcode your control reference if you do not wish to plug in other controls.

          

Payment Processing

The actual payment processing is triggered when the Checkout button is clicked. This causes the ProcessTransaction function to be called in your provider library.

Public Overrides Function ProcessTransaction(ByVal screen As ScreenName, ByVal mainView As ViewEventBooking) As Integer

 

The parameters are screen and mainView. The mainView allows us to retrieve viewstate information from the booking which will be important for processing the order. The ScreenName value allows us to test whether or not we are paying a deposit or full price and we can adapt our processing accordingly.

If the return value is > 0 then it should refer to the "signupid" which will signify a reference to all of the order participants and options booked. If this value is > 0 then the enrolment will be processed with emails being triggered and any further template processing being completed. If for example you are redirecting during this function, you need to return 0 and call the enrolment processing yourself when you receive payment notification as you will not know whether or not the transaction has been completed.

You will need several data items during this process. First off you will need the order details. You can retrieve these by making a call like so:

Dim ordArray As ArrayList = mainView.BuildOrder(screen)

 

This will return an array of line items which you can process for your order.

To retrieve the credit card details entered you need to find the controls on the form. For the "pay by deposit screen" the placeholder is called "placeDeposit". For the full payment screen it is called "placeFull". The following example shows how to get at the card details entered on the loaded form control:

CType(mainView.FindControl("placeDeposit").Controls(0).FindControl("txtCCNumber"), TextBox).Text)

 

You can replace "placeDeposit" with "placeFull" for the full price payment screen. You can do something similar for all the controls in the credit card details screen, referencing the control name in the second Findcontrol.

 

To access the signup details you use an example like the following which gets the First name field value from the "pay by deposit" screen.

 

CType(mainView.FindControl("txtDepFirstName"), TextBox).Text)

 

To process the order and to retrieve the order total do something similar to the following:

 

Dim infEventSignup As New ThirdI.Modules.EventBooking.EventSignupInfo

Dim ctlEventSignup As New ThirdI.Modules.EventBooking.EventSignupController

Dim itemcounter As Integer = 1

For Each infOrder In ordArray

Select Case infOrder.lineType

Case infOrderItems.OrderLineType.LineItem

Select Case screen

Case ScreenName.vwMakeCCPayment

infEventSignup.TotalParticipants = infEventSignup.TotalParticipants + infOrder.OrderQuantity

infEventSignup.CalculatedCost = infEventSignup.CalculatedCost + infOrder.LineTotal

itemcounter = itemcounter + 1

Case ScreenName.vwPayDeposit

infEventSignup.TotalParticipants = infEventSignup.TotalParticipants + infOrder.OrderQuantity

infEventSignup.CalculatedCost = infEventSignup.CalculatedCost + infOrder.LineTotal

itemcounter = itemcounter + 1

End Select

 

Case infOrderItems.OrderLineType.Tax

itemcounter = itemcounter + 1

 

Case infOrderItems.OrderLineType.PaypalDiscount

 

Case infOrderItems.OrderLineType.Total

ordertotal = infOrder.LineTotal

 

Case infOrderItems.OrderLineType.DiscountedTotal

ordertotal = infOrder.LineTotal

 

End Select

Next

 

Here we are creating a signup object and calculating the total. You will need to add this signup to the database and also register all participants in the database that are associated with this signup. However there is a catch. If we are redirecting, we do not wish to mark the transaction as completed yet as this will execute all the enrolment processing etc. In this case you need to save the details. You can do something like the following to achieve this:

Select Case screen

Case ScreenName.vwMakeCCPayment

signupid = mainView.RegisterSignUpDetails(infEventSignup, ScreenName.vwMakeCCPayment, SignUpStatus.InitiatedCCPayment)

Case ScreenName.vwPayDeposit

signupid = mainView.RegisterSignUpDetails(infEventSignup, ScreenName.vwPayDeposit, SignUpStatus.InitiatedDeposit)

End Select

 

 

The call to RegisterSignupDetails will save the participants and signup details to the database. The status "InitiatedDeposit|InitiatedCCPayment" will mark the transaction as incomplete. This status will also prevent the enrolment processing from executing so that you can in turn handle this in your notification function.

If you are using an API directly you may want to execute the transaction and update the booking status at the same time. For example with Authorize.NET we do something like this:

r.Code = response_array(AimField.Code)

If r.Code = 1 Then

Dim signupid As Integer = mainView.RegisterSignUpDetails(infEventSignup, screen, status)

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.AVSResponse.ToString, response_array(AimField.AVSResponse))

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.TransactionID.ToString, response_array(AimField.TransactionID))

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.InvoiceNumber.ToString, response_array(AimField.InvoiceNumber))

 

Return signupid

Else

If ActiveSettings("AUTHORIZE.NET Show error codes") = "YES" Then

lblErrorMsg.Text = response_array(AimField.ReasonString) + response_array(AimField.ReasonString) + " [CODE:" + response_array(AimField.ReasonCode) + "]" + " [SUBCODE:" + response_array(AimField.SubCode) + "]"

Else

lblErrorMsg.Text = response_array(AimField.ReasonString)

End If

 

lblErrorMsg.Visible = True

Return False

End If

 

 

Here the call to RegisterSignUpDetails is happening with the status set to completed as we have got the response code from Authorize.NET.

 

Handling the Response

You can handle the response either with a notification callback from your gateway (i.e. Paypal IPN, Payfast ITN) or with data returned from your API. Use the signupid as the unique identifier for the transaction. If you are completing the transaction in the "ProcessTransaction" function then you do not need to worry about the enrolment processing as this will occur when you return the signupid and you have saved the details with a success status in the "RegisterSignUpDetails" call. You can however update the status with transaction response code etc. In the authorize.NET example above, the relevant updates are done with this code:

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.AVSResponse.ToString, response_array(AimField.AVSResponse))

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.TransactionID.ToString, response_array(AimField.TransactionID))

ctlEventSignup.UpdateEventSignupSetting(signupid, AimField.InvoiceNumber.ToString, response_array(AimField.InvoiceNumber))

This will save the details associated with the transaction in the signupSettings table.

In the case of a postback notification, you can handle this in you page load event handler. Typically you will retrieve the signupid from the notification, retrieve the signuprecord, do whatever processing is required and update the record status. You will need to call "ProcessEnrollment" to complete the processing:

Dim vwUtil As New ViewEventBookingUtilities

If infSignup.AmountToPayOffline > 0 Then

vwUtil.ProcessEnrollment(infSignup.SignUpID, SignUpStatus.EnrolledDepositPaidOnline, PortalSettings.PortalId)

Else

vwUtil.ProcessEnrollment(infSignup.SignUpID, SignUpStatus.EnrolledPaidOnline, PortalSettings.PortalId)

End If

This call will update the signup status of the enrolment as well as handling the sending of emails and any invocations indicated if they are specified in the event ActraviaML template.

For further information and support in implementing a payment gateway please contact support@actravia.com. Full working source examples are available as part of our platinum support packages. If you need assistance we are happy to help you with custom development.

 

 

 


Your name:
Gravatar Preview
Your email:
(Optional) Email used only to show Gravatar.
Your website:
Title:
Comment:
Security Code
CAPTCHA image
Enter the code shown above in the box below
Add Comment   Cancel 
Please email support[at]actravia.com for pre-sales assistance & support. 
Contact support [@] actravia.com for assistance.