PayPal Express Checkout with PaySharp.NET

Fork me on GitHubPaySharp.NET
Express Checkout is the optimal solution for Enterprise Merchants to leverage PayPal, whose APIs are broad and intricate. This post aims to simplify the design and implementation of Express Checkout using a custom .NET library called PaySharp.NET.

Express Checkout is primarily composed of the following PayPal processes:

  1. SetExpressCheckout
  2. GetExpressCheckoutDetails
  3. DoExpressCheckoutPayment

The process flow is as follows:

PayPal Express Checkout in action

PayPal Express Checkout in action

Prerequisites

  • .NET Framework 4.5 or above

Installation

PM> Install-Package Daishi.PaySharp

Getting Started with PayPal Express Checkout

Register a Business Account with PayPal. PaySharp.NET requires the following prerequisite PayPal metadata:

  • Username
  • Password
  • Signature
  • ExpressCheckoutURI

ExpressCheckoutURI should refer to the PayPal Sandbox for all non-production environments. Each PayPal account is also associated with a Secure Merchant ID, which can be included in the Subjectfield (see code samples below), if for example, your application supports multiple currencies. This is an optional field, and is not prerequisite to fulfilling an Express Checkout transaction.

Explanation of Terms

SetExpressCheckout

Establishes a PayPal session based on Merchant credentials, and returns an Access Token pertaining to that session.

GetExpresscheckoutDetails

Returns a definitive collection of metadata that describes the PayPal user (nameaddress, etc.).

DoExpressCheckoutPayment

Collects the payment by transferring the transaction amount from the User’s account to the Merchant account.

Running the Test Harness

PaySharp.NET is covered by a range of Unit Tests, included with each build. To provide a greater degree of reliability, the SDK contains a Test Harness project. This project will execute a full Express Checkout transaction when invoked as follows:

  1. Locate App.config in Daishi.PaySharp.TestHarness
  2. Enter appropriate values for UserPasswordSignature, and Subject (if applicable)
  3. Run the project (F5)
  4. Press any key when prompted
  5. SetExpressCheckout executes and returns a PayPal Access TokenPaySharp Test Harness Step 1
  1. Open your web browser and navigate to https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1UR71602HJ0009422. Note that the token parameter is set to the value previously returned in Step 5
  2. Login to PayPal
  3. Your browser will redirect to http://www.example.com/success.html?token=EC-1UR71602HJ0009422&PayerID=783CTW8EXK5AE. Note the PayerID parameter
  4. Return to the Test Harness Command Prompt having copied the PayerID parameter from Step 3
  5. Press any key when prompted, and input the PayerID parameter from Step 3
  6. GetExpressCheckoutDetails is invokedPaySharp Test Harness Step 2
  1. Press any key when prompted
  2. DoExpressCheckoutPayment is invoked, successfully completing the transactionPaySharp Test Harness Step 3

Sample Code

SetExpressCheckout

                var user = ConfigurationManager.AppSettings["User"];
                var password = ConfigurationManager.AppSettings["Password"];
                var signature = ConfigurationManager.AppSettings["Signature"];
                var subject = ConfigurationManager.AppSettings["Subject"];

                var payPalAdapter = new PayPalAdapter();

                var setExpresscheckout =
                    payPalAdapter.SetExpressCheckout(
                        new SetExpressCheckoutPayload {
                            User = user,
                            Password = password,
                            Signature = signature,
                            Version = "108.0",
                            Amount = "19.95",
                            Subject = subject,
                            LocaleCode = "en-IE",
                            CurrencyCode = "EUR",
                            CancelUrl = "http://www.example.com/cancel.html",
                            ReturnUrl = "http://www.example.com/success.html",
                            PaymentRequestName = "TEST",
                            PaymentRequestDescription = "TEST BOOKING"
                        },
                        Encoding.UTF8,
                        ConfigurationManager.AppSettings["ExpressCheckoutURI"]);

                string accessToken;
                PayPalError payPalError;

                var ok = PayPalUtility.TryParseAccessToken(setExpresscheckout,
                    out accessToken, out payPalError);

GetExpressCheckoutDetails

                var getExpressCheckoutDetails = payPalAdapter
                    .GetExpressCheckoutDetails(
                        new GetExpressCheckoutDetailsPayload {
                            User = user,
                            Password = password,
                            Signature = signature,
                            Version = "108.0",
                            AccessToken = accessToken,
                            Subject = subject,
                            PayerID = payerID
                        },
                        ConfigurationManager.AppSettings["ExpressCheckoutURI"]);

                CustomerDetails customerDetails;

                ok = PayPalUtility.TryParseCustomerDetails(
                    getExpressCheckoutDetails, out customerDetails,
                    out payPalError);

DoExpressCheckoutPayment

                var doExpressCheckoutPayment = payPalAdapter
                    .DoExpressCheckoutPayment(
                        new DoExpressCheckoutPaymentPayload {
                            User = user,
                            Password = password,
                            Signature = signature,
                            Version = "108.0",
                            AccessToken = accessToken,
                            Subject = subject,
                            PayerID = payerID,
                            PaymentRequestAmt = "19.95",
                            PaymentRequestCurrencyCode = "EUR"
                        },
                        ConfigurationManager.AppSettings["ExpressCheckoutURI"]);

                TransactionResults transactionResults;

                ok = PayPalUtility.TryParseTransactionResults(
                    doExpressCheckoutPayment, out transactionResults,
                    out payPalError);

API Documentation

The API is fully documented; a *.chm Help-file is included with every build. If you prefer to view the API documentation in a web-based format, such as HTML, you can run the Sandcastle tool against any branch in order to generate the requisite files.

NoteYou will likely need to unblock the Help-file as part of Windows security measures.

FAQ

Does this library support C# Async?

Yes, there are asynchronous equivalents of each synchronous method exposed by the SDK.

I get weird errors from PayPal

Generally, PayPal issues intuitive error messages. Less intuitive error messages are usually returned as a result of uninitialized payload properties. In the case of SetExpressCheckout, scan through the properties in SetExpressCheckoutPayload and ensure that each property is set to an appropriate value.

Can I Fork this project?

By all means. I’m happy to contribute to any extensions.

What’s next?

An set of extensible components that make it easier for developers to create and augment objects proprietary to downstream systems, such as Fraud Prevention, Booking & Reservation, and Back-office Accounting systems.

Connect with me:

RSSGitHubTwitter
LinkedInYouTubeGoogle+

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s