README.md

PaySharp.NET

Overview

PaySharp.NET provides features that allow consuming applications and services to process PayPal Express Checkout transactions. Such transactions consist of a 7-stage process, composed of a series of browser redirects, user input, and the following PayPal mechanisms, each of which is exposed through this SDK:

• SetExpressCheckout
• GetExpressCheckoutDetails
• DoExpressCheckoutPayment

PaySharp.NET provides both synchronous and asynchronous support for each mechanism.

Process Flow

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 Subject field (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 (name, address, 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 User, Password, Signature, and Subject (if applicable)
3. Run the project (F5)
4. Press any key when prompted
5. SetExpressCheckout executes and returns a PayPal Access Token

6. 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
7. Login to PayPal
8. Your browser will redirect to http://www.example.com/success.html?token=EC-1UR71602HJ0009422&PayerID=783CTW8EXK5AE. Note the PayerID parameter
9. Return to the Test Harness Command Prompt having copied the PayerID parameter from Step 3
10. Press any key when prompted, and input the PayerID parameter from Step 3
11. GetExpressCheckoutDetails is invoked

12. Press any key when prompted
13. DoExpressCheckoutPayment is invoked, successfully completing the transaction

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.

Note: You 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.

Contact the Developer

Please reach out and contact me for questions, suggestions, or to just talk tech in general.