Stamps.

com Web Services (SWS) -

Overview

Revision v1.0.1
18 March 2009

Stamps.com Confidential

Confidential, unpublished property Stamps.com, Inc. Use and distribution

is limited solely to authorized personnel.

This document may contain confidential and privileged material for

the sole use of the intended reader. Any review or distribution by
others is strictly prohibited. If you are not the intended reader please
contact the author and delete all copies.

The use, disclosure, reproduction, modification, transfer, or transmittal of this work for any
purpose in any form or by any means without the explicit written permission of Stamps.com,
Inc. is strictly prohibited.
Table of Contents
TABLE OF CONTENTS.................................................................................................. 2
LIST OF FIGURES .......................................................................................................... 2
1 INTRODUCTION.................................................................................................... 3
2 AUTHENTICATION ............................................................................................... 4
2.1 Simple Authentication ...................................................................................................... 5
2.2 New Account Creation ...................................................................................................... 5
2.3 Forgotten Password ......................................................................................................... 5

3 PRINTING POSTAGE............................................................................................ 6
3.1 Step 1 – Standardize Shipping Address .......................................................................... 7
3.2 Step 2 – Get Rates ............................................................................................................ 7
3.3 Step 3 – Generate Shipping Label.................................................................................... 7
3.4 Step 4 – Print Shipping Label ........................................................................................... 7

4 METER REPLENISHMENT AND ACCOUNT MANAGEMENT............................. 9

5 DOCUMENT REVISION HISTORY...................................................................... 10

List of Figures
Figure 1 - Authentication Workflow....................................................................................................................... 4

Figure 2 - Printing Workflow................................................................................................................................. 6

CONFIDENTIAL Page 2 of 10 1/15/2010

Do Not Copy or Distribute
1 Introduction
Stamps.com Web Services (SWS) is an Application Programming Interface (API) to the Stamps.com system that
allows an integrator to create an application that provides calculation of USPS postage rates, standardization of
addresses via USPS CASS certified address matching software, and printing of shipping labels with integrated
postage. The integrator controls the customer experience, and Stamps.com servers handle the calculations, label
generation, and USPS compliance.

SWS primarily takes the form of web methods accessed over the internet via SOAP over HTTP. SOAP provides a
simple, common, and well-understood method of exchanging structured and typed messages between computers
using XML. SOAP itself does not define any of the semantics of a particular application, such as SWS, but instead
provides the mechanism for expressing these semantics. SWS applies the semantics that turn these simple
messages into requests from clients and responses from web services. As an open protocol published by the
World Wide Web Consortium (http://www.w3.org), extensive support is available in a variety of programming
languages and frameworks. Developers of SWS client applications are free to choose from among any one of
these or even to roll their own implementation. For more information on SOAP, see
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

While not limited to use by web-based applications, SWS was designed with the limitations of the web-based
application in mind. The labels generated by the system are delivered in the form of a URL to an image or a PDF
document. In a web-based application, the image URLs are capable of being used directly in an HTML web page
which can be shown and printed by a standard web browser. A more traditional desktop-based integration may
choose to download the image and provide its own printing mechanism.

CONFIDENTIAL Page 3 of 10 1/15/2010

Do Not Copy or Distribute
2 Authentication

Figure 1 - Authentication Workflow

The first action any integration must take is to authenticate with SWS. This requires an SWS username and
password. In the simplest case, this involves a single call to the AuthenticateUser web method. After
authentication, the integration stores a session authenticator, a token that is used when making further
communications with the SWS server.

The authentication workflow diagramed above has optional steps to allow for creation of new accounts or to allow
for a user that has forgotten their password to recover their access and establish a new password.

CONFIDENTIAL Page 4 of 10 1/15/2010

Do Not Copy or Distribute
2.1 Simple Authentication
When the username and password are known, the only web method that the integration needs to call is
AuthenticateUser. This web method will return a success status and a session authenticator when the username
and password are valid.

If an incorrect username or password are given, the web method will return a failure status and the integration
should inform the user that the password was not accepted, giving the user an opportunity to correct the
password.

A third status of password reset is a possible return value from the AuthenticateUser web method. For more
information, see 2.3 Forgotten Password.

2.2 New Account Creation

If the user does not yet have an account, the integration should allow the user to sign up for a new Stamps.com
account. This sign-up process is accomplished via a web-based registration site run by Stamps.com. The
registration site may optionally be provided with default account information provided by the integration to jump
start the registration process and save the user from entering information that is already known by the integration.
Completion of the registration process will communicate a new username back to the integration, and
authentication can proceed against the newly created account as described in 2.1 Simple Authentication.

2.3 Forgotten Password

Should the user forget his password, SWS provides web methods that will start a password reset process,
resetting the user's password to a temporary password that is sent to him by e-mail. That temporary password is
only valid for completing the password reset process, during which the user provides a new permanent password.

The forgotten password process is started by the integration when the user has indicated that they have forgotten
their password. The GetCodewordTypes web method is called to get codeword questions to ask the user. The
integration asks the answers for the codeword questions and provides those answers to the StartPasswordReset
web method. If the codeword answers are correct, a new temporary password will be sent to the user by e-mail,
using the e-mail address on file for the user. The integration should wait for the user to provide the temporary
password.

When a temporary password is used, the AuthenticateUser web method will return a status of password reset.
This is an indication to the integration that the password was temporary and the integration should get a new
permanent password from the user and call the FinishPasswordReset web method. Once the password reset
process is thus completed, the new permanent password can be used in a standard authentication as described
in 2.1 Simple Authentication.

CONFIDENTIAL Page 5 of 10 1/15/2010

Do Not Copy or Distribute
3 Printing Postage

Figure 2 - Printing Workflow

Using SWS to print postage consists of just 4 simple steps. This section will describe the basics of each of these
steps. For more detailed information, please see the full SWS reference.

CONFIDENTIAL Page 6 of 10 1/15/2010

Do Not Copy or Distribute
3.1 Step 1 – Standardize Shipping Address
Typical SWS integrations obtain shipping addresses from a database or other system, such as an order
processing application. The shipping address can also be obtained from the user. Regardless, all shipping
addresses must be standardized to conform to the USPS rules for proper address conventions before a shipping
label can be issued.

SWS provides the CleanseAddress web method for this purpose. This web method receives the shipping address
and applies the standardization rules to it, returning the standardized address as a result. This standardized
address includes a validation code that must be kept with the address when it is used later to generate a shipping
label.

The CleanseAddress web method may make changes to the address in order to standardize it. The integrator
may choose to display these changes to the user for confirmation or automatically accept the changes. If an
address cannot be standardized, but the city, state, and ZIP code are valid, SWS will still accept the address for
generation of a label. When this is the case, the integrator should warn the user that only the city, state, and ZIP
code were validated, giving them an opportunity to correct the address as it may be incorrect.

3.2 Step 2 – Get Rates

The next step of an SWS integration is to let the user make an informed choice about how to ship their package.
The user needs to know what options are allowed, how much each option will cost, and how long their package
will take to be delivered under each option.

The GetRates web method provides all of this information for a package, given its size, weight, origin, destination,
and value. An SWS integration may know this information based on information from a database or other system,
such as an order processing application. If not, this information can be obtained from the user.

The information returned from the GetRates web method contains enough information to provide the user with the
details necessary for them to make a choice of the mail class and other available services. These choices are
then passed back to SWS in the next step when the label is generated.

3.3 Step 3 – Generate Shipping Label

Once the address has been standardized and the user has chosen their shipping options, the next step is to
actually generate the shipping label. It is this step that actually deducts value from the meter.

The CreateIndicium web method is used to generate the shipping label. Assuming there is a sufficient balance
available in the meter, the cost of the label is deducted from the meter and the newly generated label is returned
to the calling application in the form of a URL to an image or PDF file.

It is important to note that once the CreateIndicium web method has been called, the postage has been deducted
from the meter. If for some reason, the shipping label is never printed or used, SWS provides a CancelIndicium
web method with which to request a refund.

3.4 Step 4 – Print Shipping Label

With the URL obtained from the previous step in hand, it is now up to the integrating application to use that URL
to print the image or PDF containing the label.

In the case of an image and a web-based integration, the integrator may choose to compose an HTML page with
an <img> tag where the src attribute of the <img> tag is the URL obtained from the CreateIndicium web method.

CONFIDENTIAL Page 7 of 10 1/15/2010

Do Not Copy or Distribute
CSS styles can be used to ensure that when the page is printed, the image of the label is scaled to be the exact
size needed, generally 4" x 6".

If the integration is not web-based, the integrator may instead just download the image from the given URL and
incorporate it into a print job that it controls in some other way.

CONFIDENTIAL Page 8 of 10 1/15/2010

Do Not Copy or Distribute
4 Meter Replenishment and Account Management
At some point, additional funds will need to be placed into the end user's meter. This can be accomplished with
the PurchasePostage web method. This web method will attempt to purchase a specified amount of postage
using the payment information on file with the user's account.

The integration may make this option available explicitly to the user or implicitly through handling of an insufficient
postage error when attempting to create a label. Either way, the integration should get confirmation from the user
before purchasing more postage.

Other account management features, such as the ability to change payment methods or contact information, are
available through Stamps.com web pages. A GetURL web method in SWS allows for a direct link into these
Stamps.com web pages that will not require the user to re-enter their password. The integrator should use this
URL to provide Stamps.com account management options to the user.

CONFIDENTIAL Page 9 of 10 1/15/2010

Do Not Copy or Distribute
5 Document Revision History
Date Draft Author Changes
23 January 2008 1.0.1 G. Begen Added authentication and postage purchase sections.
23 January 2008 1.0.0 G. Begen Initial draft.

CONFIDENTIAL Page 10 of 10 1/15/2010

Do Not Copy or Distribute