PayPal SOAP API Architecture

The PayPal SOAP API provides programmatic access to PayPal features and services. Developers can build custom applications, tools, and services that correspond to the same services and tools available through the main PayPal website, https://www.paypal.com/. Typical applications include searching for transactions, paying en masse, and making refunds.The API is based on open standards known collectively as “Web Services,” which include the Simple Object Access Protocol (SOAP), Web Services Definition Language (WSDL), and the XML Schema Definition language (XSD). These standards are supported by a wide range of development tools on a variety of platforms.

Services Architecture

Like many web services, PayPal SOAP is a combination of client-side and server-side schemas, hardware and software servers, and core services.

Figure 1.1

PayPal SOAP High-level Diagram

In an object-oriented processing model, the interface to SOAP requests/responses is an object in your application’s native programming language. Your third-party SOAP client generates business-object interfaces and network stubs from PayPal-provided WSDL and XSD files that specify the PayPal SOAP message structure, its contents, and the PayPal API service bindings. A business application works with data in the form of object properties to send and receive data by calling object methods. The SOAP client handles the details of building the SOAP request, sending it to the PayPal service, and converting the response back to an object.

PayPal WSDL/XSD Schema Definitions

The PayPal Web Services schema and its underlying eBay Business Language (eBL) base and core components are required for developing applications with the PayPal Web Services API. The following are the locations of the WSDL and XSD files.

Table 1.1

Location of PayPal WSDL and XSD Files

Development and Test with the PayPal Sandbox API Service
PayPal Schema	https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and Component Types	https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd
Production with Live PayPal Web Services API Service
PayPal Schema	https://www.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and Component Types	http://www.paypal.com/wsdl/eBLBaseComponents.xsd http://www.paypal.com/wsdl/CoreComponentTypes.xsd

API Concepts and Terminology

Here are some basic concepts and terminology relating to PayPal’s API service and security authentication.

Table 1.2

Basic PayPal API Set-up Concepts and Terminology

Term	Definition
API Calls	PayPal Application Programming Interface services, by which companies can make payments, search transactions, refund payments, view transaction information, and other business functions.
API Certificate	Mututally exclusive with API Signature. A PayPal-generated unique digital certificate file that you download from the PayPal website and use on the client computer to encrypt the HTTPS requests of your API calls to PayPal’s API server. An API certificate is suitable if you have complete control over your own web server.
API Signature	Mututally exclusive with API Signature. A PayPal-generated unique digital signature (a line of text, or hash) that you copy from PayPal’s website and include in your API calls. An alternative to API Certificate security. Your digital signature, your API username, and your API password all together are called three-token authentication, because you include each of them as a programatic token in your API calls. An API signature is suitable for use with Microsoft Windows web servers or other shared web server configurations, such as those used by web hosting services.
API Username and Password	A PayPal-generated identifying account name and password that you use specifically for making API calls. You include your API username and password with every API call. The API username and password are different from your PayPal login username (email address) and password.
Subject authorization	An indicator in an API call of the account for whom the call is being made. This is the programmatic aspect of third-party authorization. The value of the Subject field is the third-party’s Paypal email address.
First-Party Access	A company makes API calls itself from its own server to PayPal's server. The company has its own API certificate or API signature, username, and password. Example: A staff programmer for a merchant's company obtains a PayPal-issued API certificate file and makes API calls for the company from the company's own web server.
Third-Party Access	Another person or company makes API calls on the your behalf. You grant the third-party your permission to make API calls for you. Example: A web hosting service has its own API certificate, API username, and API password. Its customers, who are merchants that use PayPal, give the hosting service their permission to make API calls on their behalf. The hosting service includes a merchant's PayPal email address in the "Subject" field of an API call.

Security

The PayPal SOAP API service is protected to ensure that only authorized PayPal members use it. There are four levels of security:

1.	A required API username (Username field) and API password (Password field)

2.	A third required authentication mechanism, which is either one of the following:

–	Client-side request signing via a PayPal-issued API Certificate

–	Request authentication via an an API Signature included in the request (Signature field)

3.	An optional third-party authorization to make the API call on some other account’s behalf (the optional Subject field).

4.	Secure Sockets Layer (SSL) data transport

A failure of authenticated security at any one of these levels denies access to the PayPal SOAP API service.

SOAP RequesterCredentials: Username, Password, Signature, and Subject

For the security of your business, PayPal must verify that merchants or third-party developers are permitted to initiate a transaction before they make one. PayPal authenticates each request. If the request cannot be authenticated, a SOAP security fault is returned.

In the SOAP request header, your SOAP client must set the Username, Password elements to pass an API username/password combination. In addition, you can set the Signature or Subject elements to specify your API signature string and an optional third-party account email address for authentication. The following is a partial example of the RequesterCredentials elements required for all SOAP requests. For a correlation of these elements to the generic structure of an entire SOAP request, see “SOAP Request Envelope”.

<SOAP-ENV:Header>

<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI” xsi:type=”ebl:CustomSecurityHeaderType”>

<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents” xsi:type=”ebl:UserIdPasswordType”>

<Username>api_username</Username>

<Password>api_password</Password>

<Signature>api_signature</Signature>

<Subject>authorizing_account_emailaddress</Subject>

</Credentials>

</RequesterCredentials>

</SOAP-ENV:Header>

where:

Table 1.3

RequesterCredentials Authentication Elements in SOAP Header

Element	Value	Description
<Username>	api_username	Your API username, which is auto-generated by PayPal when you apply for a digital certificate to use the PayPal SOAP API. You can see this value on https://www.paypal.com/ in your Profile under API Access > API Certificate Information. Note: The PayPal Sandbox User Guide contains details about how you can obtain digital certificates for use with the PayPal SOAP API.
<Password>	api_password	Your API password, which you specify when you apply for a digital certificate to use the PayPal SOAP API.
<Signature>	api_signature	Your API signature, if you use one instead of an API Certificate.
<Subject>	authorizing_ account_ emailaddress	The email address of a third-party for whom you are sending requests to the PayPal SOAP API. Your API username must have been granted permission by this third-party to make any particular PayPal API request.

SOAP Service Endpoints

Depending on your chosen authentication mechanism, your SOAP requests must be processed by different service endpoints.

Table 1.4

SOAP Service Endpoints

Authentication Mechanism	Live Production Endpoint	Test (Sandbox) Endpoint
API Signature	https://api-3t.paypal.com/2.0/	https://api-3t.sandbox.paypal.com/2.0/
API Certificate	https://api.paypal.com/2.0/	https://api.sandbox.paypal.com/2.0/

Note:

For the correspondence between API calls and their service endpoints, see Table 1.8, “API Overview by Business Function”.

SOAP Implementation

This section contains information about the PayPal SOAP implementation.

SOAP Message Style: doc-literal

PayPal uses doc-literal SOAP messaging, not rpc-encoding. With doc-literal, a single service interface call passes an XML document in the request to the PayPal API server, which responds with an XML document instance.

SOAP Request Envelope

The following diagram illustrates the contents of a PayPal SOAP request envelope.

All PayPal APIs are based on two core structures: AbstractRequestType and AbstractResponseType.

Figure 1.2

Diagram of SOAP Request Envelope

Request Structure

The following is an annotated description of the SOAP request structure required by the PayPal SOAP API.

General Structure of PayPal API SOAP Request

<?xml version=”1.0” encoding=”UTF-8”?>

<SOAP-ENV:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”

><SOAP-ENV:Header>

<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”>

<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”>

<Username>api_username</Username>

<Password>api_password</Password>

<Signature/>

<Subject/>

</Credentials>

</RequesterCredentials>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

<specific_api_name_Req xmlns=”urn:ebay:api:PayPalAPI”>

<specific_api_name_Request>

<Version xmlns=urn:ebay:apis:eBLBaseComponents”>service_version
</Version>

<required_or_optional_fields xsi:type=”some_type_here”> data
</required_or_optional_fields>

</specific_api_name_Request>

</specific_api_name_Req>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Table 1.5

Annotation of Generic SOAP Request

Lines	Comment
12, 13	The <Username> and <Password> fields are part of the PayPal SOAP API <RequesterCredentials> security authentication mechanism you must construct for every SOAP request header. For details, see “SOAP RequesterCredentials: Username, Password, Signature, and Subject”.
14	The <Signature> element should include your API signature string if that is the kind of API credential you are using. For more details, see Table 1.3, “RequesterCredentials Authentication Elements in SOAP Header”.
15	The <Subject> element can specify a third-party PayPal account by whom you are authorized to make this request. For more details, see Table 1.3, “RequesterCredentials Authentication Elements in SOAP Header”.
19 through 27	The SOAP request for every PayPal API follows this element naming pattern. The API’s specific name is appended with Req, and in this element the specific_api_name_Request is nested. Each specific_api_name_Request has a corresponding specific_api_name_RequestType.
22	The number of the PayPal SOAP API version is required on each SOAP request. This version number is the value of ns:version in https://www.paypal.com/wsdl/PalPalSvc.wsdl
24	For details about required and optional elements and values for specific requests, see the description of individual APIs.

Response Structure

The following is an annotated description of the structure of a SOAP response from the PayPal API where response is Success:

 

 

 

 

 

 

<?xml version=”1.0”?>

<SOAP-ENV:Envelope
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
xmlns:cc=”urn:ebay:apis:CoreComponentTypes”
xmlns:wsu=”http://schemas.xmlsoap.org/ws/2002/07/utility”
xmlns:saml=”urn:oasis:names:tc:SAML:1.0:assertion”
xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”
xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xmlns:ebl=”urn:ebay:apis:eBLBaseComponents”
xmlns:ns=”urn:ebay:api:PayPalAPI”>

<SOAP-ENV:Header>

<Security
xmlns=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xsi:type=”wsse:SecurityType”
/>

<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>

<Credentials
xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”
/>

</RequesterCredentials>

</SOAP-ENV:Header>

<SOAP-ENV:Body id=”_0”>

<specific_api_name_Response xmlns=”urn:ebay:api:PayPalAPI”>

<Timestamp xmlns=”urn:ebay:api:PayPalAPI”>
dateTime_in_UTC/GMT
</TIMESTAMP>

<Ack xmlns=”urn:ebay:apis:eBLBaseComponents”>Success</Ack>

<Version xmlns=”urn:ebay:apis:eBLBaseComponents”>
serviceVersion
</Version>

<CorrelationId xmlns=”urn:ebay:apis:eBLBaseComponents”>
applicationCorrelation
</CorrelationID>

<Build xmlns=”urn:ebay:apis:eBLBaseComponents”>
api_build_number
</Build>

<elements_for_specific_api_response>
data
</elements_for_specific_api_response>

</specific_api_name_Response>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Table 1.6

Annotation of Generic SOAP Response

Lines	Comment
22 and 31	The specific_api_name_Response start and end elements.
23	Each API response contains a timestamp with its date and time in UTC/GMT.
24	The <Ack> element contains the string Success after the corresponding request has been successfully processed. (For a complete list of possible returned strings, see “AbstractResponseType”.) In the case of errors, Ack is set to a value other than Success, and the response body contains an <Errors> element with information to help you troubleshoot the cause of the error. See “Error Responses”.
26	The <CorrelationID> element contains information about the PayPal application that processed the request. Use the value of this element if you need to troubleshoot a problem with one of your requests.
27 through 30	The different PayPal APIs return different structures depending on their response definitions. For detailed information, see the description of the individual APIs. Note: Because a field is defined in the formal structure of an API response does not mean that that field is necessarily returned. Data are returned in a response only if PayPal has recorded data that corresponds to the field.

Error Responses

If a request is malformed or some other error, the body of the SOAP response contains an <Errors> element with other elements that can help you troubleshoot the cause of the error. The most important of these additional elements are as follows:

l	ShortMessage

l	LongMessage

l

ErrorCode

For a description of the contents of these elements, see Appendix A, “Error Codes and Messages for All PayPal APIs.”

The following example shows the error response if your API username and password do not match a legitimate API username and password on file with PayPal.

Example of SOAP Error Response: Bad Username or Password

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope details not shown>

<SOAP-ENV:Header>... details not shown.</SOAP-ENV:Header>

<SOAP-ENV:Body id="_0">

<GetTransactionDetailsResponse xmlns="urn:ebay:api:PayPalAPI">

<Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">
2005-02-09T21:51:26Z
</Timestamp>

<Ack xmlns="urn:ebay:apis:eBLBaseComponents"> Failure</Ack>

<Errors
xmlns="urn:ebay:apis:eBLBaseComponents"
xsi:type="ebl:ErrorType">

<ShortMessage xsi:type="xs:string">
Authentication/Authorization Failed
</ShortMessage>

<LongMessage xsi:type="xs:string">
Username/Password is incorrect
</LongMessage>

<ErrorCode xsi:type="xs:token">10002</ErrorCode>

<SeverityCode xmlns="urn:ebay:apis:eBLBaseComponents">
Error
</SeverityCode>

</Errors>

<CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents">
debugging_info
</CorrelationID>

<Version xmlns="urn:ebay:apis:eBLBaseComponents">
1.000000
</Version>

<Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>

.. other elements in response.

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

CorrelationID for Reporting Problems to PayPal

The value returned in CorrelationID is important for PayPal to determine the precise cause of any error you might encounter. If you have to troubleshoot a problem with your requests, we suggest that you capture the value of CorrelationID so you can report it to PayPal.

PayPal SOAP API Definitions

The PayPal SOAP API comprises individual API definitions for specific business functions. As a foundation, the API relies on eBay Business Language (eBL) base and core components. The core eBL structures AbstractRequestType and AbstractResponseType are the basis of the SOAP request and response of each PayPal API. AbstractResponseType is also the framework for error messages common across all PayPal APIs.

PayPal has made some schema design decisions that can affect how businesses design their own applications.

l	Enumerations: Enumerations are defined directly in the PayPal API schema.

l	Troubleshooting information: The PayPal API returns information about elements that trigger errors.

l	Backward compatibility: The PayPal API is versioned so that business applications are backward compatible when new elements are introduced to the server-side schema.

Note:

eBL defines many structures that are specific to processing auctions. PayPal’s SOAP schema includes these definitions to maintain compatibility with eBay’s SOAP and for possible future joint use of SOAP across both eBay and PayPal. The material in this book focuses only on those SOAP definitions pertinent to use of the PayPal SOAP API.

Character Encoding, Data Types and Formats, and Currencies

This section details allowed character encoding and character sets, date data types, and formats.

UTF-8 Character Encoding

The PayPal SOAP API service assumes that all data in SOAP requests is in Unicode, specifically, the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8).

In SOAP responses, the service always returns data in UTF-8.

Date/Time Formats

The PayPal SOAP API schema defines date/time values as Coordinated Universal Time (UTC/GMT), using ISO 8601 format, and of type ns:dateTime. An example date/time stamp is 2006-08-24T05:38:48Z

PayPal-Supported Transactional Currencies

The following currencies are supported by PayPal for use in transactions.

Table 1.7

PayPal-Supported Currencies and Currency Codes for Transactions

ISO-4217 Code	Currency
AUD	Australian Dollar
CAD	Canadian Dollar
CHF	Swiss Franc
CZK	Czech Koruna
DKK	Danish Krone
EUR	Euro
GBP	Pound Sterling
HKD	Hong Kong Dollar
HUF	Hungarian Forint
JPY	Japanese Yen
NOK	Norwegian Krone
NZD	New Zealand Dollar
PLN	Polish Zloty
SEK	Swedish Krona
SGD	Singapore Dollar
USD	U.S. Dollar

Core Currency Amount Data Type

The core currency amount data type is call BasicAmountType and is derived from string, and all currency amount fields have the following structure:

1.	The currencyID attribute is required.

2.	The amount must have two decimal places.

3.	The decimal separator must be a period (“.”).

4.	You must not use any thousands separator.

5.

BasicAmountType has a data type of ebl:CurrencyCodeType, which defines a large number of different currency codes. However, for your processing to succeed, you must set currencyCode to one of the values from the first column of “PayPal-Supported Transactional Currencies”. Some APIs support only a subset of these currencies.

Here is an example. (The field name Amount is an example; actual field names can vary depending on the specific API.)

<Amount currencyID=”currencyCode”>3.00</Amount>

API Overview By Business Function

The PayPal SOAP API consists of individual APIs for specific business uses.

Table 1.8

API Overview by Business Function

Business Function	SOAP Request/Response
Authorization & Capture	DoCapture DoAuthorization DoVoid DoReauthorization
Direct Payment	DoDirectPayment
Express Checkout	SetExpressCheckout GetExpressCheckoutDetails DoExpressCheckoutPayment
Get Transaction Details	GetTransactionDetails
MassPay	MassPay
Refund Transaction	RefundTransaction
Transaction Search	TransactionSearch
Recurring Payments	CreateRecurringPaymentsProfile GetRecurringPaymentsProfileDetails ManageRecurringPaymentsProfileStatus UpdateRecurringPaymentsProfile BillOutstandingAmount SetCustomerBillingAgreement
Reference Transaction (direct payments only)	DoReferenceTransaction
Non-referenced credit	DoNonReferencedCredit

Instant Payment Notification and the APIs

Use of a PayPal API that results in an exchange of funds triggers the sending of an Instant Payment Notification. The issuer of the API call is the one who receives the IPN. With the exception of MassPay, the API response contains all information you need about a transaction

For more information about Instant Payment Notification, see the PayPal Order Management Integration Guide.