Announcement

As of April 17, 2018, this site is now in read-only mode. To start new Blackbaud Developer’s discussions, you will find Developer Discussions in the Blackbaud CRM Community.

To post or respond to Blackbaud Community discussions, you will have to login using a www.blackbaud.com login. Learn how to login here. If you have questions or need assistance, please email community@blackbaud.com.

Using Blackbaud Secure Payments from a custom BBIS part – Part One

By: Joseph Styons

Posted on: August 22, 2014

 

Blackbaud offers a Secure Payment service, creatively named “Blackbaud Secure Payments”.

This service provides a secure way to accept credit card payments from constituents, without having to deal with the security concerns of handling that data yourself.

 

When you think of the BBSP user experience, you can compare it to PayPal.

Your form does it’s thing (buy a membership! sign up for an event! donate now!), then the user clicks “Pay now” and they are redirected to another page.

That page collects their payment information, they click “submit”, and then they come back to your site (A “Thank you’ page, perhaps).

 

The key is that your site never touches the payment information directly.

You simply get a yes/no answer from the payment service about whether their payment was successful, or not.

This post is going to be about how to get started with using that service.

 

First, there are a few prerequisites.  This time, the whole team gets to share in making this work – it’s not just for developers.

Business: You must have subscribed to the BBSP service.

Technical: You must be on version 3.0, SP5 or higher.

Administrative: You must enter valid credentials under Administration->Sites & Settings->Web Services->Blackbaud Payment Services

 

Once you have all of that in place, you can process payments using BBSP.

This post will focus on how to do that from within a custom part.

 

In your Visual Studio project, add a new item.

Choose “Blackbaud CMS” on the left hand side, and choose “Part” on the right hand side.

Give your part a name – something like “PaymentTest” would be fine.

This will result in three new files in your project – a Display part, an Editor part, and a Properties class.

image_thumb.png

We will begin with the Display part.

Place a textbox on the form.  Call it “txbAmount”.  Put a button on the form.  Call it “btnSubmit”.  Make the caption of the button read “Donate now!”.

There.  That will be all of our markup for now.

Your page should look like this:

image.png

Now, double-click on the “donate now” button to create an event handler for it.  Paste in this code.

 

1
2
3
4
5
6
7
8
9
10
11
12
Protected Sub btnSubmit_Click(sender As Object, e As EventArgs) Handles btnSubmit.Click
    'this will show up on the payment page as a header     Const description As String = "Your organization name"
    'replace this value with one that works for you, using the query     Dim merchantAccountID As Guid = New Guid("select * from ClientMerchantAccounts")
    Dim amount As Decimal = 0.0
    Decimal.TryParse(txbAmount.Text, amount)
    'put together our request to BBSP into a consolodated object     Dim paymentTransaction = API.SecurePayments.CardNotPresent(merchantAccountID, Nothing, amount, Nothing, String.Empty, description, False)
    'this will take us away to the BBSP page     API.SecurePayments.Redirect(paymentTransaction) End Sub

 

Notice the New Guid() contains a sql statement.

Run that statement in your database, and get the value for the Merchant Account you want to use for processing this payment.

Put that guid in the place of the sql statement.

 

Now, go up to the Page_Load event of your part.  Paste in this code:

1
2
3
4
5
6
7
8
9
10
11
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
    'if they just completed payment, then we will be coming back to this page with a token in our URL.     If Not BBSPTransactionID.Equals(Guid.Empty) Then
        Dim transactionResult As BBNCExtensions.API.DataObjects.SecureTransactionInfo = API.SecurePayments.TransactionResponse(BBSPTransactionID)
        If transactionResult IsNot Nothing AndAlso ProcessingResultCode.Approved = transactionResult.ResultCode Then
            lblError.Text = "Payment was approved!"
        Else
            lblError.Text = "Payment was not approved"
        End If
    End If End Sub

 

You should get a syntax error on the “If not bbsp…” line.  That’s because we need to use a new base class to support our new BBSP functionality.

Go up to this line:

1
Inherits BBNCExtensions.Parts.CustomPartDisplayBase

And change it to this, instead:

1
Inherits BBNCExtensions.Parts.CustomPartBBSPDisplayBase

Finally, add this line to the top of your file:

1
Imports Blackbaud.AppFx.BBPay.ServiceProxy

 

Now, your code should compile, and you should be able to deploy the part, register it in BBIS, drop it on a page, and try it out.

Note that a valid entry for testing is:

Card Type: Visa

Card number: 4111111111111111

Security Code: 123

Expiration: Anything in the future

 

If it works, then clicking “submit” should take you to a BBSP page like this one:

 

image_thumb.png

 

This is just the beginning of our coverage of BBSP.

Future topics include:

How to pre-populate the fields on the payment form with values from your customization

How to change the look and feel of the payment page with template uploads

How to retrieve non-critical data entered on the BBSP page, such as the entered email address and last four of the credit card

How to write a robust customization that handles the following scenarios:

Successful payment

Failed payment

The user clicks “Cancel” on the payment form

Confirmation pages and emails

Letting custom URL parameters survive the payment process

Obligatory link to the handbook

3 thoughts on “Using Blackbaud Secure Payments from a custom BBIS part – Part One

  1. Thanks for the article. I was wondering if there was going to be a part 2 out soon? I interested in some of the future topics that you mention, and wasn’t sure if I needed to just contact Blackbaud SDK support. I haven’t been able to find any documentation items such as “How to change the look and feel of the payment page with template uploads”.

  2. Thanks for the interest – I haven’t forgotten about the follow up posts, but I don’t have a definite date in mind. If you need an immediate response, then you should probably ask support.

Leave a Reply

Privacy Policy | Sitemap | © 2011 Blackbaud, Inc. All Rights Reserved

Digital Ocean