Welcome to the Windows 8 Checkout SDK

The PayPal Windows 8 Checkout SDK gives you the ability to integrate PayPal payment functionality into the apps you create for the Windows 8 Store and the Windows 8 Phone.

PayPal is the most trusted payment system for online transactions, and offering PayPal as a payment method lets your customers be secure with the transactions they complete with your app. In addition to offering secure payments, PayPal also gives you the ability to sell digital goods from within your app, which is a unique offering among Microsoft platform payment methods. Accepting PayPal can open new revenue streams because you can sell addition program content and software updates from within your Windows app.

Windows 8 Checkout SDK uses Mobile Express Checkout for its underlying technology, and it offers the same functionality with the same pricing model. Before integrating the SDK requests into your Windows 8 app, make sure you understand how to complete a Mobile Express Checkout transaction as described in the Mobile Express Checkout Getting Started Guide.

Overview

To integrate PayPal payments into your Windows 8 applications:

  1. Configure Visual Studio with the PayPal Visual Studio extension.
  2. Create the needed PayPal merchant and test accounts.
  3. Call the interfaces from your app.
  4. Test the payment functionality.
  5. Launch your app on the Windows App Store.

Note  To develop Windows 8 applications, you must develop on the Windows 8 OS and use Visual Studio 2012.

Windows 8 Store vs. Windows 8 Phone integrations

You can integrate Windows 8 Checkout SDK into both Windows 8 Store applications and Windows 8 Phone apps. The Windows 8 Checkout SDK uses a Windows Runtime Component for the Store applications, while Windows Phone apps make use of a Portable Class library. The main differences between these two integration types are summarized in the following table:

Integration Type Library File Languages Supported
Windows 8 Store PayPal.Checkout.vsix XAML + C#
XAML + C++
JavaScript
Windows 8 Phone PayPal.Checkout.SDK-WindowsPhone8.dll C#

Setting up the SDK

Setting up the SDK for usage is a two-step process.

1. Install the SDK library files

The PayPal Windows 8 Checkout SDK page contains the latest version of the SDK library files.
Download and configure the SDK files according to the type of app you’re creating:

Windows 8 Store applications
Download and run PayPal.Checkout.vsix to install the library for global use.
Windows 8 Phone apps
Download PayPal.Checkout.SDK-WindowsPhone8.dll into your project's lib directory.

2. Reference the SDK from your project

To make use of the PayPal Windows 8 Checkout SDK in your Visual Studio projects:

  1. Launch Visual Studio 2012 and open up the Windows 8 project to which you’re adding the PayPal checkout functionality.

  2. Right-click References in the Solution Explorer and select Add Reference.

    • For Store applications, navigate to Windows > Extensions, select PayPal Checkout SDK and click OK.

    • For Phone apps, browse to the PayPal.Checkout.SDK-WindowsPhone8.dll file and click OK.

      On the My Accounts tab, click Profile, then My Selling tools. Click Update for API Access.
      The Solution Explorer

You’re now ready to make calls to the Windows 8 Checkout interfaces. Time to code!

PayPal accounts in SDK requests

Each PayPal transaction in a Windows 8 app involves three different PayPal accounts:

  • The receiver account: The business account that receives (or refunds) the transaction funds.
  • The caller account: The app account used to authenticate the API calls made from your app.
  • The sender account: The payer account, also known as the buyer or customer account.

Your requests through the SDK reference these PayPal accounts by either their API credentials or by their associated PayPal account details (the PayPal account email or user ID value).

Important: As you develop your app and go live, you will make use of two different sets of user accounts. One is the set of Sandbox test accounts that you use while testing. The other set of accounts represent the real users that partake in the live transactions that your app generates as it runs in production. You configure the different live and test account values in the SDK.

The receiver and sender accounts

In live transactions, the receiver account is a live PayPal Business account. This is your live merchant account. When testing, configure a Sandbox Business test account that you use as the receiver.

The sender account in live transactions is the customer who uses your Windows app. For testing purposes, you configure a Sandbox Personal test account to represent the buyer.

Note  When you create a new PayPal Business account, PayPal pre-configures a Sandbox Business account that you can use in your test transactions. However, you must still create a Sandbox Personal account to act as the buyer in your mock PayPal transactions. See _Creating a Personal test account in Testing Classic API Calls for details on creating test accounts and using the PayPal Sandbox.

The caller account

The caller account is a PayPal account that is explicitly configured to run with Windows Checkout SDK. Using a Pre-configured account protects your API credentials from being exposed and simplifies the transaction processing. You reference the caller account by their associated PayPal User ID values, as defined in the following table:

Pre-configured Windows App caller accounts
Environment PayPal Caller Account User ID
Sandbox mswin_1352404208_biz_api1.paypal.com
Live windowsstore_api1.paypal.com

API caller permissions

It’s important to understand the relationship between the caller and receiver accounts. The caller account makes API calls on behalf of the receiver account. Because of this, you must grant permission for the caller account to make requests on the behalf of your merchant account.

During the development process, you will grant permission twice, once for the Sandbox Business (merchant) account and once for your live merchant account. The process for granting permissions for each account type is nearly identical, the only difference is the environment you use to assign the permissions. You assign permissions for your live merchant account from the account settings on PayPal.com (https://paypal.com). For testing, you assign permissions from your Business test account using the Sandbox test site (https://www.sandbox.paypal.com).

To assign permissions for your Business test account:

  1. Log in to the Sandbox test site using the log-in credentials of your Business test account.

    Note: You must first sign in to the Developer website using your merchant account before you can sign in to the Sandbox test site using the login credentials from one of your test accounts.

  2. Select My Account > Profile > My Selling Tools, then click the Update (API Access) link:

    On the My Accounts tab, click Profile, then My Selling tools. Click Update for API Access.
    Navigating to the API Access page

    If you’re already logged in to the Sandbox site with your receiver test account, you can navigate directly to the API Access page using the following link: . https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_profile-api-list-auths

  3. On the API Access page, click Grant Permissions under Option 1.

    The Add New Third Party Permissions page displays.

  4. In the Third Party Permission Username input box, enter the User ID of the caller account to which you are granting permissions, and click the Lookup button.

    • Use mswin_1352404208_biz_api1.paypal.com for the Sandbox environment.
    • Use windowsstore_api1.paypal.com for the live environment.
  5. From the list of Available Permissions, check the following boxes, then click add to establish the permissions:

    • Use Express Checkout to process payments
    • Use Express Checkout to process mobile payments
  6. (Optional) If your situation requires, configure your account to accept payments for Digital Goods. If you do not, users will not be allowed to purchase digital goods from your app using the SDK. See Accepting a Basic Digital Goods Payment Using Express Checkout for more information.

That’s all you need to do to configure your accounts to use SDK! Notice that for testing, you only need to add SDK permissions to your Sandbox Business account, you need not update any configuration settings for your Sandbox Personal test accounts.

For more information on granting permissions and making calls on behalf of a third-party, see the Permissions Service Getting Started Guide.

Processing PayPal transactions

The following diagram shows the process flow of a Windows 8 Checkout SDK transaction:

 

The Windows 8 Checkout SDK app flow.
The Windows 8 Checkout SDK app flow

Here’s the flow:

  1. Your app sends a purchase request to PayPal, including information describing the item (or cart of items) to be purchased, and the authentication information for the PayPal buyer account.

  2. Upon approval of the payment, PayPal responds to your app with the following:

  • Token - Authentication token unique to the transaction.
  • Transaction ID - Used in subsequent requests associated with the transaction.
  • Payer ID - Uniquely identifies the payer and needed to verify the payment.

Running your app in test mode

Make sure your app runs as expected by testing its functionality using the Sandbox text accounts you’ve configured. While testing, use a Personal test account to represent the buyer in your test transactions.

To test your app, run your app and click the Purchase Item button to have your app launch the PayPal login page. Use the login credentials from your buyer test account to sign into the PayPal Sandbox.

From here you can complete or cancel the purchase. When you complete a purchase, transaction records are sent to both your Sandbox Personal and Business (merchant) accounts.

The following diagram shows how the transaction process looks to your app user:

 

The user flow.
The user flow

When testing, complete or cancel the transaction as you expect your users will; the Sandbox is a self-contained environment where you can review your transaction results from both the payer and payee’s standpoints. Create a robust application by testing all process flows to ensure your app gracefully handles all user actions. Streamline your PayPal transaction processing, then push your app to production.

Launching your app

The next step is to launch your app in the Windows App Store. Configure your app to go live as follows:

  1. In the SDK, set BuyNow.UseSandbox = false.

    This configures the SDK to use the live PayPal account values you entered, instead of using the configured Sandbox values.

  2. Follow the directions in the API Caller Permissions section above to configure the permissions for your live merchant account.

You app is now ready to be submitted for certification as a Windows App and once certified, you can launch the app in the Windows App Store and start collecting profits! For details, see Using the Windows Store dashboard.

Next steps

See the following documents and examples for more info: