The ASP.NET and Classic ASP SDKs for the SOAP API

The SDK is composed of API Services, Encrypted Website Payments (EWP) Services, and user profiles that define characteristics of the users of those services. This section includes the following topics:

l	“Installing the SDK”

l	“Configuring the SDK”

l	“API Services”

l	“Profiles”

l	“COM-Specific Classes”

l	“Sample Applications”

Installing the SDK

This section details the software and hardware supported and required by the PayPal SDK, installation, and post-installation tasks.

Supported Standards

The PayPal SDK has been verified to work with the following standards.

Table C.1

Supported Standards

Standard	Version
Microsoft .NET Framework	1.1, Service Pack 1
Simple Object Access Protocol (SOAP)	1.1
Web Services Description Language (WSDL)	1.1

Supported Human Languages

U.S. English

SDK Version Number

PayPal ASP.NET and Classic ASP SDKs version 4.3.1

Minimum Hardware Requirements

The following table lists the minimum hardware requirements for using the PayPal SDK in development and testing. Production systems might require more capacity, depending on their expected load.

Table C.2

Minimum System Hardware Requirements

Component	Minimum Capacity
RAM	256 MB
CPU	Pentium 1 GHz
Disk space	50 MB

Software Requirements

Microsoft .NET Framework 1.1, Service Pack 1

Note:

You can download Service Pack 1 from the Microsoft web site.

Downloading and Installing the SDK

The latest version of the PayPal SDK is available at https://www.paypal.com/sdk. You can download either a self-extracting installation program or a ZIP file.

The installation is straightforward and requires no special instruction. Installing the SDK source is optional.

SDK Directories

The SDK components are organized into different subdirectories, as shown in Table C.3, “PayPal SDK Directories and Contents.”

Table C.3

PayPal SDK Directories and Contents

Directory	Descrption
bin	Compiled SDK DLLs and the SDK console (Console.exe)
docs	Ndoc class documentation and SDK guide
samples\ASPNET or ClassicASP	Example programs that use the SDK, in subdirectories
samples\cert	sdk-seller.p12 API certificate for API user sdk-seller_api1.sdk.com
src	Visual Studio project files and SDK source files. This folder is present only if you installed the source of the SDK.

Uninstalling the SDK

To uninstall the SDK, use the Microsoft Windows control panel Add/Remove Programs.

Installing the Samples

The SDK comes with sample applications for your study and use. These samples can be installed in Microsoft Internet Information Server. For information, see “Sample Applications”.

Configuring the SDK

This section describes how to configure the SDK to work with the sample applications and programs you develop.

Referencing the SDK DLLs for ASP.NET

Before developing applications with the SDK, be sure to add references in your ASP.NET projects to the SDK dynamic load libraries (DLLs) in SDK_root\bin.

Modifying the Web.config File

You can modify the PayPal ASP.NET and Classic ASP SDK behavior by making changes to the Web.config configuration file.

Initializing the Web.config File for Classic ASP

The Classic ASP SDK relies on a Web.config configuration file:

SDK_root\Samples\ClassicASP\Web.config

To enable logging for your SDK-based web applications, the SDK must know the location of its Web.config file. In your Global.asa file, modify the Session_OnStart method to call the SDK’s COMAdapter.Init method:

Sub Session_OnStart

Set pp_caller = CreateObject("com.paypal.sdk.COMNetInterop.COMAdapter") pp_caller.Init Request.ServerVariables("APPL_PHYSICAL_PATH")

End Sub

Note:

This step is not necessary for ASP.NET.

Optional Custom Configurations in Web.config

You can add optional custom settings to the Web.config file.

Immediately after the top-level <configuration> tag, you see a <configSections> tag. In <configSections>, add a <section name=”paypal”> tag, as shown below.

<configuration>

<configSections>

<section name=”paypal” type=”com.paypal.sdk.core.ConfigSectionHandler, paypal_base”/>

<configSections>

The optional custom settings are in a <paypal> block later in the file:

<paypal>

... custom settings ...

</paypal>

Setting Maximum Retries of SOAP Requests

In the <paypal> block in Web.config, you can set the maximum number of retries to send SOAP requests.

<maximumRetries value=”integerNumberOfRetries”/>

A value of 0 for integerNumberOfRetries sends a SOAP request once, with no retries. The default setting is 0.

PayPal recommends setting maximumRetries no greater than 3.

SDK Logging

The PayPal SDK uses log4net public domain logging software. For information about log4net, see the log4net documentation at http://logging.apache.org/log4net/release/manual/introduction.html.

This section describes SDK logging levels, the configuration files in which you set the desired level, and SOAP request logging.

Log Levels

The SDK varies the amount of detail it records according to four logging levels.

Table C.4

SDK Logging Levels

Level	Description
ALL	Same as DEBUG
ERROR	Log only severe errors
INFO	Date/time of API operation, operation name, elapsed time, success or failure indication
DEBUG	Full text of SOAP requests and responses and other debugging messages. DEBUG logging can degrade the performance of the SDK. Be careful about using it for day-to-day operation. Note: Because SOAP requests and responses are asynchronous, the recording of requests and responses might appear out of sequence in the log file.

Setting SDK Log Levels

To enable logging for your SDK-based web applications, add the following lines inside the <configuration> block of the Web.config file. You can copy these lines from the SDK_root\samples\ASPNET\Web.config or SDK_root\samples\ClassicASP\Web.config file.

l	You can change the value of the file element to write log records to a specific location.

l	Set the value of the level element to the desired detail described in Table C.4, “SDK Logging Levels.”

<configSections>

<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>

</configSections>

<log4net>

<appender name="PAYPALLOGFILE" type="log4net.Appender.RollingFileAppender">

<file value="logs/paypal.sdk.log" />

<appendToFile value="true" />

<encoding value="UTF-8" />

<rollingStyle value="5" />

<maxSizeRollBackups value="10" />

<maximumFileSize value="10MB" />

<staticLogFileName value="true" />

<layout type="log4net.Layout.PatternLayout">

<conversionPattern value="%d{dd MMM yyyy HH:mm:ss} %-5p [%C{1}] %m%n" />

</layout>

</appender>

<logger name="com.paypal.sdk"> <level value="ALL" />

<appender-ref ref="PAYPALLOGFILE" />

</logger>

</log4net>

SOAP Request Logging

To enable logging of the full text of SOAP requests and responses, add the following lines inside the <system.web> block of your Web.config file. You can copy these lines from the SDK_root\samples\ASPNET\Web.config or SDK_root\samples\ClassicASP\Web.config file.

IMPORTANT:

DEBUG logging can degrade the performance of the SDK. Be careful about using it for day-to-day operation.

<webServices>

<soapExtensionTypes>

<add type="com.paypal.sdk.logging.DefaultSOAPHandler, paypal_base" priority="1" group="0" />

</soapExtensionTypes>

</webServices>

Enabling Proxy Support for ASP.NET

If your application is behind a proxy server, you must enable proxy support in the Web.config file. For details on how to use the system.net element in the Web.config file, please refer to Configuring Internet Applications in the MSDN Library.

API Services

Integrated access to the PayPal Web Services APIs is one of the main features of the PayPal SDK. As shown in Figure C.1, “PayPal SDK API Services: High-Level View”, the PayPal SDK uses the underlying platform’s SOAP toolkit to communicate with the PayPal API endpoint. Stub classes representing the requests, the responses, and their data are provided to set request parameters and read response values. These classes are auto-generated from the PayPal WSDL file.

Figure C.1

PayPal SDK API Services: High-Level View

Complete SDK and API Class Documentation

Complete Microsoft .NET Ndoc documentation for all PayPal SDK interfaces, classes, methods, structures, and data types are included with the SDK distribution. To view the documentation, open the following file with your web browser:

SDK_root/docs/PayPalBaseAPI.chm

Profiles

Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes:

l	A PayPal API username and password.

l	If you are using API Certificates, the path to the API certificate in P12 format and the private key password to that certificate.

l	If you are using API Signatures, the signature string.

l	The name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject. This name is optional.

l	The PayPal environment for processing API calls: live, sandbox or beta-sandbox.

An Encryted Wweb Payments (EWP) profile is associated with EWP services includes:

l	The path to the merchant’s local copy of that public certificate

l	The private key password for that public certificate

l	The path to a merchant’s private key file for digitally signing data

l	The URL to which the button form POSTs

l	The optional URL of a payment button image. The default is PayPal’s standard Buy Now button.

For more information about how EWP works, see the Website Payments Standard Integration Guide.

Overview to Profile-related Classes

The primary interfaces and classes for SDK profiles are described below.

Table C.5

Summary of ASP.NET and Classic ASP SDK Profile-related Interfaces and Classes

Interface/Class	Description
IAPIProfile interface	This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of IAPIProfile for each account that accesses the APIs. For single-merchant developers, only a single IAPIProfile instance is needed. PayPal provides a default implementation class called DefaultAPIProfile suitable for the needs of most SDK developers. However, can write a custom implementation if you need additional functionality the default class does not offer.
ProfileFactory class	This class creates IAPIProfile object. It contains static methods that handle the instantiation and construction of profile objects.
EWPProfile interface	This interface defines the basic information that PayPal needs to know about a user of PayPal’s Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code for single-merchant users. This will be just be a single instance. PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you can write a custom implementation if you need functionality the default class does not offer.

COM-Specific Classes

COM developers can use of the following classes:

l	COMAdapter2

l

COMArray

l

COMUtil

These classes are in the com.paypal.sdk.COMNetInterop namespace. For examples of them in use, see the source code in SDK_Root\Samples\ClassicASP.

COMAdapter2

The COMAdapter2 class includes methods for setting and retrieving the values associated with an API profile, including the API username and password, the API signature, the third-party subject and the environment. It also includes methods for making API calls.

The older COMadapter class is for backward-compatibility.

For example, the following code snippet sets the API Profile to the credentials of the sample user supplied with the PayPal SDK, as described in “Sample Applications”.” This sample user relies on an API certificate:

Set pp_caller = CreateObject("com.paypal.sdk.COMNetInterop.COMAdapter2")

' Set API profile

pp_caller.SetAPIUsername "sdk-seller_api1.sdk.com"

pp_caller.SetAPIPassword "12345678"

' Set the third-party subject to null

pp_caller.SetSubject ""

pp_caller.SetEnvironment “sandbox”

The following code snippet sets the API Profile to the credentials of a user who relies on an API signature:

 

' Set API profile

pp_caller.SetAPIUsername "seller_api1.designerfotos.com"

pp_caller.SetAPIPassword "5GM8R4SNEPLGP524"

' Set the API Signature string

pp_caller.SetAPISignature "A0iFR8ojMS.TH8Eyc3t0CP1dTJzbA.cDbvQAR0GPJVEuvtDzkiPJNKj7"

' Set the third-party subject to null

pp_caller.SetSubject ""

pp_caller.SetEnvironment “sandbox”

COMArray

The COMArray proxy class functions similarly to the .NET ArrayList class. Use COMArray when you need to create a .NET array when you are setting up the request object; for example, when you provide multiple PaymentDetailsType items to a DoDirectPayment request.

For example:

<%

Dim pmtDetailsItemArray

Set pmtDetailsItemArray = CreateObject("com.paypal.sdk.COMNetInterop.COMArray")

Dim pmtDetailsItem1

Set pmtDetailsItem1 = CreateObject("com.paypal.soap.api.PaymentDetailsItemType")

pmtDetailsItemArray.Add(pmtDetailsItem1)

Dim paymentDetailsType

Set paymentDetailsType = CreateObject("com.paypal.soap.api.PaymentDetailsType")

pmtDetailsItemArray.SetField paymentDetailsType, "PaymentDetailsItem"

%>

COMUtil

The COMUtil utility class facilitates populating enumerated values in request objects.

For example, suppose you want to specify US Dollars as the Currency type in a DoDirectPayment call. Without the COMUtil class, you would need to specify the integer value of the enumeration with code such as the following:

Set .Amount = CreateObject("com.paypal.soap.api.BasicAmountType")

.Amount.currencyID = 21

Instead, you can use the COMUtil class as follows:

Set util = CreateObject("com.paypal.sdk.COMNetInterop.COMUtil")

Set .Amount = CreateObject("com.paypal.soap.api.BasicAmountType")

.Amount.currencyID = util.GetEnumValue("CurrencyCodeType", "USD")

Sample Applications

The PayPal SDK includes sample applications in the SDK_root\samples\ASPNET or SDK_root\samples\ClassicASP folder. The samples are divided into subfolders by products.

Table C.6

Samples by Product

Subfolder in SDK_Root\samples\ASPNET or ClassicASP	Products
admin	DoCapture
	DoVoid
	GetTransactionDetails
	MassPay
	RefundTransaction
	TransactionSearch
	DoReauthorization
wppro	Express Checkout l Final Sale l Authorization l Order
	Direct Payment API l Final Sale l Authorization

Sample API User with API Signature

The samples come with an API Signature for use with the SDK and the PayPal Sandbox. This API Signature belongs to the following user:

Table C.7

Details of the SDK Sample API Signature

API Username	sdk-three_api1.sdk.com
API Password	QFZCWN5HZM8VBG7Q
API Signature	A‑IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

Sample API User and Certificate

The samples come with a PayPal Web Services API digital certificate for use with the SDK and the PayPal Sandbox. This certificate belongs to the following user:

Table C.8

Details of the sdk-seller.p12 SDK Sample Certificate

Location of Certificate	SDK_root\samples\Certs\sdk-seller.p12
API Username	sdk-seller_api1.sdk.com
API Password	12345678
PKCS12 Passphrase	password

Installing the Samples in IIS

Note:

Be sure that you are logged in as an administrator, that IIS running, and that WinHttpCertCfg.exe is in your PATH.

To install the samples in Microsoft IIS:

1.	Run one of the following:

SDK_root\samples\ASPNET\InstallSample.bat.

SDK_root\samples\ClassicASP\InstallSample.bat.

2.	For ASP.NET To enable logging, change the permissions on the localComputerName\ASPNET folder to Full Control.

For Classic ASP: To enable logging, for the user account that has anonymous access, change the permissions on the logs folder to Full Control. By default, this folder is named IUSER_localComputerName.

InstallSample.bat does the following:

–	Creates a virtual directory named PaypalASPNETSample or PaypalClassicASPSample in IIS that points to SDK_root\samples\ASPNET or ClassicASP.

–	Loads the sample API certificate SDK_root\samples\Certs\sdk-seller.p12 into the Microsoft Windows system store.

–	Uses the WinHttpCertCfg.exe command to grant unlimited access for account Everyone to that certificate .

Running the Samples

To run the samples, open one of the following URLs in an internet browser:

http://localhost/PaypalASPNETSamples

http://localhost/PaypalClassicASPSamples