PayPal Mobile Checkout - 2009 Developer's Guide

Mobile Checkout Developer Guide
Last updated: October 2009
Mobile Checkout Developer Guide
Document Number: 10044.en_US-200910
© 2009 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349. Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability: PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 1 PayPal Mobile Checkout Overview . . . . . . . . . . . . . 7
Security on the Mobile Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How Mobile Checkout Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Customer Activation for Mobile Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Mobile Checkout Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Merchant Integration Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Initiating the Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Redirecting to PayPal Mobile Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 12
Completing the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2 Mobile Checkout API Reference . . . . . . . . . . . . . . .15
SetMobileCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SetMobileCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SetMobileCheckout Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
DoMobileCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
DoMobileCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . . 20
DoMobileCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . . 20
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Appendix A PayPal Supported Currencies . . . . . . . . . . . . . . . .31
Appendix B Country Codes . . . . . . . . . . . . . . . . . . . . . . . 33
Mobile Checkout Developer Guide October 2009 3
4 October 2009 Mobile Checkout Developer Guide

Preface

This Guide

The Mobile Checkout Developer Guide describes the PayPal Mobile Checkout service. It describes the interfaces, information flows, and functionality of this service.

Intended Audience

This guide is written for developers of mobile applications that use PayPal. You should be familiar with mobile website programming and with either the PayPal Web Services API or the PayPal Name-Value Pair API Interface.

Revision History

Revision history for Mobile Checkout Developer Guide.
TABLE P.1 Revision History
Date Description
October 2009 Updated the list of supported currencies and currency codes.
May 2008 Added general API error codes.
September 2007
May 2007 Initial version of document.
z Added information about secure Return and Cancel URLs z Noted that PIN is recommended but not required.

Where to Go for More Information

This guide relies on information in the following guides and references:
z Express Checkout Integration Guide z Name-Value Pair API Developer Guide z SOAP API Developer Reference z Sandbox User Guide
Mobile Checkout Developer Guide October 2009 5
6 October 2009 Mobile Checkout Developer Guide
1

PayPal Mobile Checkout Overview

PayPal Mobile Checkout provides merchants with the essential components necessary for mobile commerce:
z A hosted quick buyer flow z A straightforward merchant interface z Transaction completion data z PayPal merchant support
PayPal defines mobile commerce as any and all transactions completed using a mobile phone. Buyers use a simple two step process (login and review) to make payments. The merchant interface can be plugged into any mobile medium that can initiate a mobile browser session, and uses either the PayPal Web Services SOAP or Name/Value Pair (NVP) API interface. After a transaction is completed, the necessary buyer and transaction data is delivered to the merchant via the interface.
The processing flow and APIs for Mobile Checkout are similar to those for Express Checkout. For more information about Express Checkout, see the Name-Value Pair (NVP) Developer Guide and Reference and the SOAP API Reference.

Security on the Mobile Web

PayPal Mobile Checkout is designed to support the vast majority of mobile devices sold by major carriers that can make secure connections. To access mobile checkout, a device, mobile carrier, and browser must support the following:
z WAP 2.0 phones (not WAP 1.0) z xHTML or HTML markup language z SSL connections z Cookies enabled z No carrier "WAP gap"
If a device or connection fails any of the these checks, the customer will not be able to connect to the PayPal servers.
N OTE: Mobile web generally refers to the collection of accepted web standards used on
mobile devices. Most modern mobile devices use mini-browsers, much like a web browser on a computer. A growing portion of phone subscribers pay for data plans to access information, services, and commerce on their mobile devices though these mobile browers. Most mobile browsers use the xHTML markup language, while others also use cHTML, HTML, and WML. Most devices support cookies with default
Mobile Checkout Developer Guide October 2009 7
PayPal Mobile Checkout Overview
1

How Mobile Checkout Works

on and support SSL connections. However, not all devices meet these standards or have implemented these standards to the associated specification.
How Mobile Checkout Works
1. After selecting products to purchase, your customers click a Checkout with PayPal link or button on your mobile site or in a Short Message Service (SMS) text message.
2. They are transferred to PayPal, where they log in, review and select their payment method and the correct shipping address.
3. The customer is returned to your mobile site to complete the transaction. PayPal returns to you the shipping address, email, and other customer information needed to fulfill the order.

Availability

Only authorized business and premier merchants have access to the Mobile Checkout API. For more information, contact your PayPal Account Manager.

Customer Activation for Mobile Checkout

Because numeric characters are easier to enter on a phone than an alphanumeric password, the PayPal Mobile Checkout flow encourages customers to create a numeric PIN to use for future transactions. The process of creating a numeric PIN is known as activation. In the checkout flow, customers can activate their phones on the PayPal website or as part of the checkout process when using Mobile Checkout.
If the customer has previously activated their phone, they log into PayPal Mobile Checkout using their phone number and PIN. If the customer is not activated, they must enter their PayPal user name (email) and password. They can then optionally create a new PIN. Depending on the information PayPal gets about the phone number from cookies or the API call, PayPal presents either the user name and password login option or the phone number and PIN option.
Figure 1.1 illustrates the login flow for activated customers. Figure 1.2 illustrates the login
flow for non-activated customers.
8 October 2009 Mobile Checkout Developer Guide
FIGURE 1.1 Activated Mobile Checkout Flow
F
IGURE 1.2 Non-Activated Mobile Checkout Flow
PayPal Mobile Checkout Overview
Customer Activation for Mobile Checkout
1
Mobile Checkout Developer Guide October 2009 9
PayPal Mobile Checkout Overview
1

Mobile Checkout Processing Flow

Mobile Checkout Processing Flow
Table 1.1 shows the generic processing flow of a Mobile Checkout transaction. The Merchant
column entries in bold represent integration points, which are described in more detail in subsequent sections.
TABLE 1.1 Mobile Checkout Processing Flow
Customer Merchant PayPal
Selects product from merchant mobile site, website, client, or SMS keyword list
Displays product details and gives customer the option to pay with PayPal.
Selects PayPal by clicking link to open PayPal Mobile Checkout
Logs in to PayPal flow and selects funding.
Confirms transaction on merchant site, if necessary
Calls SetMobileCheckout API to initiate transaction
Receives API call and returns response containing transaction token.
Redirects customer to PayPal URL with token appended
Starts PayPal flow.
Redirects customer to merchant­supplied, secure Return URL.
Calls DoMobileCheckoutPayment API to complete transaction
Displays order confirmation page
10 October 2009 Mobile Checkout Developer Guide
PayPal Mobile Checkout Overview
Mobile Checkout Processing Flow
Figure 1.3, “Mobile Checkout Processing Flow,” illustrates the processing flow for a Mobile
Checkout Transaction.
FIGURE 1.3 Mobile Checkout Processing Flow
1
Mobile Checkout Developer Guide October 2009 11
PayPal Mobile Checkout Overview
1

Merchant Integration Points

Merchant Integration Points
This section describes the merchant integration points shown in bold in Table 1.1.

Initiating the Transaction

When the customer clicks the Checkout with PayPal link or button, initiate the PayPal transaction with a call to the SetMobileCheckout API. You can call SetMobileCheckout using either PayPal SOAP Web Services or the PayPal Name-Value Pair (NVP) API. The SetMobileCheckoutRequest contains the following information:
z Shopping cart information, including billing, tax, and shipping amounts and currencies z PayPal flow information, including Return URL and Cancel URL
IMPORTANT: Always use a secure site for the return URL. Mobile browsers may not
smoothly handle the transition from secure sites (https) to unsecure sites (http) and may display warning messages or experience delays.
z Customer information (optional), including name, phone number, shipping address, and e-
mail)
If you include the customer’s phone number, e-mail address, or shipping address in the SetMobileCheckout request, these values are used as defaults within the PayPal flow. See
“SetMobileCheckout Request” on page 15 for more information about specific request fields.
The SetMobileCheckout response contains a Tok en , which identifies the transaction at subsequent integration points. The token times out after 24 hours.

Redirecting to PayPal Mobile Checkout

After the response from SetMobileCheckout, you must redirect the customer’s browser to PayPal. The SetMobileCheckout response contains a session token field, t. Add the value of the token to the following URL and direct the customer’s browser to it in the following form:
https://mobile.paypal.com/wc?t=<Token>
For example:
https://mobile.paypal.com/wc?t=Q234AD23AF92821
N OTE: Redirecting the customer to https://mobile.paypal.com/wc?t=<Token>
ensures best performance. However, you can also redirect to https://www.paypal.com/wc?t=<Token>.
PayPal gets details about the customer (such as shipping address and payment method) and then returns control back to the ReturnURL field from the SetMobileCheckout request. This URL should be the final review page, if provided, where the customer confirms the order and payment, or the confirmation page.
12 October 2009 Mobile Checkout Developer Guide

Completing the Transaction

After the customer has confirmed the transaction on your mobile site, complete the transaction by calling the DoMobileCheckoutPayment API. The DoMobileCheckoutPayment request contains the token from the SetMobileCheckout response.
N OTE: If you do not call DoMobileCheckoutPayment, the transaction is not completed.
The token returned by SetMobileCheckout times out after 24 hours. If you call DoMobileCheckoutPayment with a expired token, an error is returned.
PayPal returns a DoMobileCheckoutPayment response, which contains the following information:
z Customer information (including name, shipping address, and e-mail) z Payment information (PayerInfo type, including billing, tax, and shipping amounts, and
other transaction information)
PayPal Mobile Checkout Overview
Merchant Integration Points
1
Mobile Checkout Developer Guide October 2009 13
PayPal Mobile Checkout Overview
1
Merchant Integration Points
14 October 2009 Mobile Checkout Developer Guide

Mobile Checkout API Reference

2
This chapter provides detailed specifications for the request and response fields for the following Mobile Checkout APIs:
z SetMobileCheckout
z DoMobileCheckoutPayment
You can call these APIs using SOAP or Name-Value Pair (NVP). Field information for both SOAP and NVP are provided.

SetMobileCheckout

Call this API to initiate a mobile checkout transaction. The response returns a token that uniquely identifies the transaction. You must then redirect
the customer’s mobile browser to the following URL:
https://mobile.paypal.com/wc?t=<Token>
N OTE: Redirecting the customer to https://mobile.paypal.com/wc?t=<Token>
ensures best performance. However, you can also redirect to https://www.paypal.com/wc?t=<Token>.
You must have approval from PayPal in order to use this API. Contact your PayPal Account Manager for more information.

SetMobileCheckout Request

TABLE 2.1 SetMobileCheckout Request
SOAP NVP Description Data Type Req?
BuyerPhone. CountryCode
PHONE COUNTRYCODE
Three-digit country code for buyer’s phone number. Character length and limit: 3 single-byte characters Currently, only 1 and 44 are supported..
ebl:Count ryCodeTyp e
No
Mobile Checkout Developer Guide October 2009 15
Mobile Checkout API Reference
2
SetMobileCheckout
T
ABLE 2.1 SetMobileCheckout Request
SOAP NVP Description Data Type Req?
BuyerPhone. PhoneNumber
ItemAmount AMT Cost of item before tax and shipping.
ItemAmount. CurrencyID
Tax TAXAMT Tax on item purchased.
PHONENUM Localized phone number used by the buyer to submit
the payment request (excludes country code). If the phone number is activated for Mobile Checkout, PayPal uses this value to pre-fill the PayPal login page.
Character length and limit: 9 to 13 single-byte characters
Character length and limitations: Must not exceed $1,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N OTE: You must also set the
ItemAmount.CurrencyID field.
CURRENCY CODE
A three-character currency code. Default: USD. For allowable values, see
Supported Currencies
Character limit: 3 single-byte characters
N OTE: The tax amount must be in the same currency
as the ItemAmount.
Appendix A, “PayPal
.”
xs:string No
cc:Basic AmountTyp e
ns:Curren cyCodeTyp e
cc:Basic AmountTyp e
Ye s
Ye s
No
Shipping SHIPPINGAMT The shipping costs for this transaction.
N OTE: The shipping amount must be in the same
currency as the ItemAmount.
Character length and limitations:
ItemName DESC The name of the item being ordered.
Character length and limitations: 127 single-byte characters
ItemNumber NUMBER Pass-through field allowing you to specify details,
such as SKU. Character length and limitations: 127 single-byte
characters
16 October 2009 Mobile Checkout Developer Guide
cc:Basic AmountTyp e
xs:string Ye s
xs:string No
No
Mobile Checkout API Reference
SetMobileCheckout
T
ABLE 2.1 SetMobileCheckout Request
SOAP NVP Description Data Type Req?
2
Custom CUSTOM This element is a passthrough variable. Its value is
returned verbatim on the final PayPal Mobile Checkout API, DoMobileCheckoutPayment. You can use this value for whatever purpose you desire, such as an accounting tracking number or additional data needed by your applications (for example, a session ID or other variable).
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID INVNUM Your own invoice number or ID used to identify the
transaction. Character length and limitations: 127 single-byte
alphanumeric characters
ReturnURL RETURNURL The customer’s browser returns to this URL after
choosing to pay with PayPal. The token is appended to this URL as follows:
https://www.example.com/confirmorder?to ken=<Token>
I MPORTANT: Always use a secure site for the return
URL. Mobile browsers may not smoothly handle the transition from secure sites (https) to unsecure sites (http) and may display warning messages or experience delays.
N OTE: PayPal recommends that the URL be the final
review page on which the customer confirms the order and payment.
xs:string No
xs:string No
xs:string Ye s
Character length and limitations: no limit.
CancelURL CANCELURL The customer is returned to this URL if they cancel
payment from within the PayPal flow by clicking the Cancel or Return to Merchant buttons.
I MPORTANT: Always use a secure site for the
cancel URL. Mobile browsers may not smoothly handle the transition from secure sites (https) to unsecure sites (http) and may display warning messages or experience delays.
N OTE: PayPal recommends that the value be the
original page on which the customer chose to pay with PayPal.
Character length and limitations: no limit
Mobile Checkout Developer Guide October 2009 17
xs:string No
Mobile Checkout API Reference
2
SetMobileCheckout
T
ABLE 2.1 SetMobileCheckout Request
SOAP NVP Description Data Type Req?
Address Display
ADDRESS DISPLAY
Options
SharePhone SHARE
PHONENUM
ShipTo Address
Table 2.2
See
on page 19
Indicates whether a shipping address is required for the transaction. Valid values are:
z 0 – A shipping address is not required. Default. z 1 – A shipping address is required. If you pass a
value for ShippingAddress, that address is displayed.
N OTE: Displaying the PayPal street address on file
does not allow the customer to edit that address.
Indicates whether the customer’s phone number is returned to the merchant. The customer will be notified in the flow that the phone number is required by the merchant, and can select not to provide the number.
Allowable values:
z 0 – Phone number not returned. Default. z 1 – Phone number returned.
The customer’s shipping address as stored by the
.
merchant. If this address is specified, it is displayed during checkout. If not, the customer’s default shipping address is displayed during checkout.
See
Table 2.2 on page 19. If you specify a Ship To
address, you must enter the fields marked as required in
Table 2.2 on page 19.
xs:string No
xs:string No
ebl:Addre
No
ssType
N OTE: If a confirmed address is required by the
merchant’s profile, then only confirmed addresses are displayed.
BuyerEmail EMAIL Email address of the buyer as entered during
checkout. If the phone number is not activated for Mobile Checkout, PayPal uses this value to pre-fill the
ns:EmailA ddressTyp e
No
PayPal login page. Character length and limit: 127 single-byte
alphanumeric characters
18 October 2009 Mobile Checkout Developer Guide
Mobile Checkout API Reference
SetMobileCheckout
TABLE 2.2 Ship To Address Fields
SOAP NVP Description Data Type Required
2
Name SHIPTO
NAME
Street1 SHIPTO
STREET
Street2 SHIPTO
STREET2
CityName SHIPTO
CITY
StateOr Province
Country SHIPTO
SHIPTO STATE
COUNTRY
Person’s name associated with this shipping address.
Character length and limitations: 32 single-byte characters
Street address line 1. Character length and limitations: 300 single-byte
characters
Street address line 2. Character length and limitations: 300 single-byte
characters
Name of city. Character length and limitations: 120 single-byte
characters
State or province. Character length and limitations: 120 single-byte
characters
ISO 3166 country code. For allowable values, see
.”
Codes
Character limit: 2 single-byte characters
Appendix B, “Country
xs:string No
xs:string Yes
xs:string No
xs:string Yes
xs:string No
ns:Country CodeType
Ye s
PostalCode SHIPTO
ZIP
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
xs:string No

SetMobileCheckout Response

T
ABLE 2.3 SetMobileCheckout Response
SOAP NVP Description Data Type
Token TOKEN A timestamped token that uniquely identifies this transaction.
N OTE: The token expires after 24 hours.
Character length and limitations: 20 single-byte characters
Mobile Checkout Developer Guide October 2009 19
xs:string
Mobile Checkout API Reference
2

DoMobileCheckoutPayment

DoMobileCheckoutPayment
Call the DoMobileCheckoutPayment API to process the customer’s payment. If DoMobileCheckoutPayment is successful, PayPal processes the payment.

DoMobileCheckoutPayment Request

TABLE 2.4 DoMobileCheckoutPayment Request
SOAP NVP Description Data Type Required
Token TOKEN A timestamped token that uniquely identifies this transaction.
Use the token returned in SetMobileCheckout response.
N OTE: The token returned by SetMobileCheckout
expires after 24 hours.
Character length and limitations: 20 single-byte characters
xs:string Ye s

DoMobileCheckoutPayment Response

T
ABLE 2.5 DoMobileCheckoutPayment Response
SOAP NVP Description Data Type
Custom CUSTOM This element is a passthrough variable. Its value is
returned verbatim as set in the SetMobileCheckout request. You can use this value for whatever purpose you desire, such as an accounting tracking number or additional data needed by your applications (for example, a session ID or other variable).
Character length and limitations: 256 single-byte alphanumeric characters
xs:string
InvoiceID INVNUM Your own invoice or tracking number, as set by you in
the element of the same name in SetMobileCheckout request .
Character length and limitations: 127 single-byte alphanumeric characters
PayerInfo See
Table 2.7
Information about the customer. See Table 2.7 on
page 24
.
xs:string
ebl:PayerInfo Type
on page 24
20 October 2009 Mobile Checkout Developer Guide
Mobile Checkout API Reference
DoMobileCheckoutPayment
T
ABLE 2.5 DoMobileCheckoutPayment Response
SOAP NVP Description Data Type
2
PaymentInfo See
Table 2.6
Information about the payment. See Table 2.6 on
page 21
.
ebl:PaymentInfo Type
on page 21
ABLE 2.6 DoMobileCheckoutPayment Response: PaymentInfo Type
T
SOAP NVP Description Data Type
TransactionID TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 19 single-byte characters
Parent TransactionID
PARENT TRANSACTIONID
Parent or related transaction identification number. This field is populated for the following transaction types:
z Reversal. z Capture of an authorized transaction. z Reauthorization of a transaction. z Capture of an order. The value of
ParentTransactionID is the original OrderID.
z Authorization of an order. The value of
ParentTransactionID is the original OrderID.
z Capture of an order authorization. z Void of an order. The value of ParentTransactionID
is the original OrderID.
Character length and limits: 16 digits in xxxx-xxxx­xxxx-xxxx format (19 characters total)
xs:string
xs:string
ReceiptID RECEIPTID Receipt identification number.
xs:string
Character length and limits: 16 digits in xxxxxxxx­xxxx-xxxx format
Transaction Type
PaymentType PAYMENTTYPE Indicates whether the payment is instant or delayed.
TRANSACTION TYPE
The type of transaction. The transaction type for mobile payments is send-money, as if the customer created the transaction from the PayPal website.
Possible values are:
z none z instant
ns:Payment Transaction CodeType
ns:Payment CodeType
Character length and limitations: 7 single-byte characters
PaymentDate ORDERTIME Date and time of payment. xs:dateTime
Mobile Checkout Developer Guide October 2009 21
Mobile Checkout API Reference
2
DoMobileCheckoutPayment
T
ABLE 2.6 DoMobileCheckoutPayment Response: PaymentInfo Type
SOAP NVP Description Data Type
GrossAmount AMT Full amount of the customer's payment, before
transaction fees are subtracted. This amount includes any shipping and taxes from your Merchant Profile.
Character length and limitations: Does not exceed $1,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,).
GrossAmount. Currency
FeeAmount FEEAMT PayPal fee amount charged for the transaction.
FeeAmount. Currency
SettleAmount SETTLEAMT Amount deposited in your PayPal account after a
CURRENCYCODE Currency code for the gross amount.
For possible values, see
Supported Currencies
N OTE: A single NVP field is returned for the currency
code for GrossAmount, FeeAmount, SettleAmount, and TaxAmount.
Character length and limitations: No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,).
CURRENCYCODE Currency code for the gross amount.
For possible values, see
Supported Currencies
currency conversion.
Appendix A, “PayPal
.”
Appendix A, “PayPal
.”
cc:Basic AmountType
ns:Currency CodeType
cc:Basic AmountType
ns:Currency CodeType
cc:Basic AmountType
SettleAmount. Currency
TaxAmount TAXAMT Tax charged on the transaction.
TaxAmount.Cur rency
ExchangeRate EXCHANGERATE Exchange rate if a currency conversion occurred.
22 October 2009 Mobile Checkout Developer Guide
CURRENCYCODE Currency code for the gross amount.
For possible values, see
Supported Currencies
Character length and limitations: No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,).
CURRENCYCODE Currency code for the gross amount.
For possible values, see
Supported Currencies
Relevant only if your are billing in the customer’s non­primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account.
Character length and limitations: a numeric value that does not exceed 17 characters, including decimal point
Appendix A, “PayPal
.”
Appendix A, “PayPal
.”
ns:Currency CodeType
cc:Basic AmountType
ns:Currency CodeType
xs:string
Mobile Checkout API Reference
DoMobileCheckoutPayment
T
ABLE 2.6 DoMobileCheckoutPayment Response: PaymentInfo Type
SOAP NVP Description Data Type
2
PaymentStatus PAYMENTSTATUS Status of a PayPal payment.
Status of the payment:
z Completed – The payment has been completed,
and the funds have been added successfully to your account balance.
z Pending – The payment is pending. See the
PendingReason element for more information.
PendingReason PENDINGREASON The reason the payment is pending:
z none – No pending reason. z address – The payment is pending because your
customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.
z intl – The payment is pending because you hold a
non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.
z multi-currency – You do not have a balance in
the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.
z verify – The payment is pending because you are
not yet verified. You must verify your account before you can accept this payment.
z unilateral – The payment is pending because it
was made to an email address that is not yet registered or confirmed.
z upgrade – The payment is pending because it was
made via credit card and you must upgrade your account to Business or Premier status in order to receive the funds. upgrade can also mean that you have reached the monthly limit for transactions on your account.
z other – The payment is pending for a reason other
than those listed above. For more information, contact PayPal customer service.
ns:Payment StatusCode Type
ReasonCode REASONCODE The reason for a reversal if PaymentStatus is
reversed. This field is always empty for Mobile
Checkout.
Mobile Checkout Developer Guide October 2009 23
ns:Reversal ReasonCode Type
Mobile Checkout API Reference
2
DoMobileCheckoutPayment
TABLE 2.7 DoMobileCheckoutPayment Response: PayerInfo Type
SOAP NVP Description Data Type
Payer EMAIL Payer’s e-mail address.
Character length and limitations: 127 single-byte characters.
PayerID PAYERID Unique PayPal customer account
number. Character length and limitations: 17
single-byte characters.
PayerStatus PAYERSTATUS Status of the payer’s email address. ns:PayPalUserStatusCodeType
PayerName See
PayerCountry COUNTRYCODE Payer’s country code.
Table 2.8
on page 24
Payer’s name. See Table 2.8 on
page 24
For possible values, see
.
ns:EmailAddressType
ns:UserIDType
ebl:PayerNameType
ns:CountryCodeType
Appendix B, “Country Codes.”
Character length and limitations:2 single-byte characters.
PayerBusiness BUSINESS Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address See
Table 2.9
on page 25
Payer’s address. See Table 2.9 on
page 25
.
xs:string
ebl:AddressType
ContactPhone PHONENUM Phone number shared by the
customer with the merchant.
ABLE 2.8 DoMobileCheckoutPayment Response: PayerName Type
T
SOAP NVP Description Data Type
ebl__ Salutation
ebl__First Name
ebl__Middle Name
ebl__Last Name
ebl__Suffix SUFFIX Payer’s suffix ns:SuffixType
24 October 2009 Mobile Checkout Developer Guide
SALUTATION Payer’s salutation ns:Salutation
FIRSTNAME Payer’s first name ns:NameType
MIDDLENAME Payer’s middle name ns:NameType
LASTNAME Payer’s last name ns:NameType
xs:string
Type
Mobile Checkout API Reference
DoMobileCheckoutPayment
TABLE 2.9 DoMobileCheckoutPayment Response: Address Type
SOAP NVP Description Data Type
2
Name NAME Person’s name associated with shipping address.
Character length and limitations: 32 single-byte characters
Street1 SHIPTO
STREET
Street2 SHIPTO
STREET2
CityName SHIPTO
CITY
StateOr Province
Country SHIPTO
SHIPTO STATE
COUNTRY
Street address line 1. Character length and limitations: 300 single-byte
characters
Street address line 2. Character length and limitations: 300 single-byte
characters
Name of city. Character length and limitations: 120 single-byte
characters
Name of state or province. Character length and limitations: 120 single-byte
characters
ISO 3166 country code. For possible values, see
.”
Codes
Character length and limitations: Two single-byte characters
Appendix B, “Country
xs:string
xs:string
xs:string
xs:string
xs:string
ns:Country CodeType
PostalCode SHIPTOZIP U.S. Zip code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phone SHIPTOPHONE
NUM
Address Owner
Address Status
ADDRESS OWNER
ADDRESS STATUS
Phone number associated with this address.
eBay company that maintains this address: eBay or
PayPal
Status of the address on file with PayPal:
None
Confirmed
Unconfirmed
xs:string
ebl:AddressOw nerTypeCode
ebl:AddressSt atusCodeType
Mobile Checkout Developer Guide October 2009 25
Mobile Checkout API Reference
2

Error Codes

Error Codes
This section contains error codes that you may encounter in your application. Your application may receive the following types of errors:
z Mobile Checkout Error Codes z General API Errors
TABLE 2.10 Mobile Checkout Error Codes
Error Code Short Message Long Message Description
10001 Internal Error Internal Error Internal API Error.
10800 Internal Error Internal Error Mobile Checkout Internal Error.
10801 Internal Error Internal Error Account is locked or restricted.
10802 Internal Error Internal Error System is unavailable.
10806 Internal Error Internal Error Problem completing payment.
10808 Internal Error Internal Error No funding source available to
complete the request.
10809 Internal Error Internal Error Invalid recipient email/phone.
10810 Internal Error Internal Error Cannot send a payment to
yourself.
10811 Internal Error Internal Error Recipient cannot receive
payments.
10812 Internal Error Internal Error Problem completing payment.
10813 Internal Error Internal Error No funds held in recipient’s
preferred currency .
10814 AddressDisplayOptions must
be 1 because your payment receiving preferences require the buyer to choose a confirmed.
10815 Internal Error Internal Error Recipient’s payment receiving
AddressDisplayOptions must be 1 because your payment receiving preferences require the buyer to choose a confirmed.
Recipient does not have a confirmed address. For SetMobileCheckout, either specify
AddressDisplayOption = 1 or change payment receiving
preferences to not require a confirmed address.
preferences do not allow this transaction.
10823 Internal Error Internal Error Attempted to share address or
phone to an unregistered phone or email, which is not allowed.
26 October 2009 Mobile Checkout Developer Guide
Mobile Checkout API Reference
Error Codes
T
ABLE 2.10 Mobile Checkout Error Codes
Error Code Short Message Long Message Description
10824 Internal Error Internal Error All specified amounts must
have the same currency.
2
10825 BuyerPhone is not supported
by PayPal Mobile.
10826 Internal Error Internal Error Checkout session not completed
10827 Internal Error Internal Error Invalid token.
10828 Internal Error Internal Error Token has expired.
10829 ShipToAddress is ignored
because your payment receiving preferences require the buyer to choose a confirmed address.
10830 ShipToAddress was an invalid
address.
10831 BuyerPhone is an invalid
phone number.
10833 Payment has already been
made for this InvoiceID.
10834 Internal Error Internal Error Specified token does not belong
BuyerPhone is not supported by PayPal Mobile.
ShipToAddress is ignored because your payment receiving preferences require the buyer to choose a confirmed address.
ShipToAddress was an invalid address.
BuyerPhone is an invalid phone number.
Payment has already been made for this InvoiceID.
Phone is valid but is not supported by PayPal Mobile (such as a country where the service is not yet available.
by the buyer.
Ship To address ignored.
Invalid shipping address.
Invalid phone number.
Duplicate invoice number.
to the merchant making this API call.
10835 Internal Error Internal Error Payments to this merchant are
not available from the country where the buyer account is registered.
10836 Internal Error Internal Error Payments to this merchant are
not available from the country where a bank or credit card on the buyer’s PayPal account is registered.
Mobile Checkout Developer Guide October 2009 27
Mobile Checkout API Reference
2
Error Codes
TABLE 2.11 General API Errors
Short
Error Code
Message Long Message Correcting This Error
10002 Authentication
/Authorization Failed
10002 Authentication
/Authorization Failed
10002 Authentication
/Authorization Failed
10002 Internal Error Internal Error
10002 Authentication
/Authorization Failed
10002 Authentication
/Authorization Failed
Username/Password is incorrect This error can be caused by
You do not have permissions to make this API call
Account is locked or inactive
Internal Error
Account is not verified
an incorrect API username, an incorrect API password, or an invalid API signature. Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error.
10002 Authentication
/Authorization Failed
10002 Authentication
/Authorization Failed
10002 Restricted
account
10002 Authentication
/Authorization Failed
10002 Authentication
/Authorization Failed
28 October 2009 Mobile Checkout Developer Guide
This call is not defined in the database!
Token is not valid
Account is restricted Your PayPal merchant
account has been restricted. Contact your PayPal account manager for resolution.
Token is not valid
API access is disabled for this account
ABLE 2.11 General API Errors
T
Short
Error Code
Message Long Message Correcting This Error
Mobile Checkout API Reference
Error Codes
2
10002 Authentication
/Authorization Failed
10002 Restricted
account
Client certificate is disabled
Account is restricted
Mobile Checkout Developer Guide October 2009 29
Mobile Checkout API Reference
2
Error Codes
30 October 2009 Mobile Checkout Developer Guide
A

PayPal Supported Currencies

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.
TABLE A.1 PayPal-Supported Currencies and Currency Codes
Currency Currency Code
Australian Dollar AUD
Brazilian Real
N OTE: This currency is supported as a payment currency
and a currency balance for in-country PayPal accounts only.
Canadian Dollar CAD
Czech Koruna CZK
Danish Krone DKK
Euro EUR
Hong Kong Dollar HKD
Hungarian Forint HUF
Israeli New Sheqel ILS
Japanese Yen JPY
Malaysian Ringgit
N OTE: This currency is supported as a payment currency
and a currency balance for in-country PayPal accounts only.
Mexican Peso MXN
BRL
MYR
Norwegian Krone NOK
New Zealand Dollar NZD
Philippine Peso PHP
Polish Zloty PLN
Pound Sterling GBP
Singapore Dollar SGD
Swedish Krona SEK
Mobile Checkout Developer Guide October 2009 31
PayPal Supported Currencies
A
T
ABLE A.1 PayPal-Supported Currencies and Currency Codes
Currency Currency Code
Swiss Franc CHF
Taiwan New Dollar TWD
Thai Baht THB
U.S. Dollar USD
32 October 2009 Mobile Checkout Developer Guide
B
Country Code
AFGHANISTAN AF
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA DZ
AMERICAN SAMOA AS
ANDORRA AD

Country Codes

N OTE: This table lists country codes defined by ISO 3166-1.
Table 1: Country Codes
ANGOLA AO
ANGUILLA AI
ANTARCTICA AQ
ANTIGUA AND BAR­BUDA
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
AG
BARBADOS BB
Mobile Checkout Developer Guide October 2009 33
Country Codes
B
Country Code
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO
BOSNIA AND HERZE-
BA
GOVINA
BOTSWANA BW
BOUVET ISLAND BV
BRAZIL BR
BRITISH INDIAN
IO
OCEAN TERRITORY
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN
CF
REPUBLIC
CHAD TD
CHILE CL
CHINA CN
34 October 2009 Mobile Checkout Developer Guide
Country Code
CHRISTMAS ISLAND CX
Country Codes
B
COCOS (KEELING)
CC
ISLANDS
COLOMBIA CO
COMOROS KM
CONGO CG
CONGO, THE DEMO-
CD CRATIC REPUBLIC OF THE
COOK ISLANDS CK
COSTA RICA CR
COTE D'IVOIRE CI
CROATIA HR
CUBA CU
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
EQUATORIAL GUINEA GQ
ERITREA ER
ESTONIA EE
ETHIOPIA ET
Mobile Checkout Developer Guide October 2009 35
Country Codes
B
Country Code
FALKLAND ISLANDS
FK (MALVINAS)
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN
TF TERRITORIES
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUATEMALA GT
GUERNSEY GG
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HAITI HT
36 October 2009 Mobile Checkout Developer Guide
Country Code
Country Codes
B
HEARD ISLAND AND
HM MCDONALD ISLANDS
HOLY SEE (VATICAN
VA CITY STATE)
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRAN, ISLAMIC REPUB-
IR LIC OF
IRAQ IQ
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KOREA, DEMOCRATIC
KP PEOPLE'S REPUBLIC OF
KOREA, REPUBLIC OF KR
KUWAIT KW
Mobile Checkout Developer Guide October 2009 37
Country Codes
B
Country Code
KYRGYZSTAN KG
LAO PEOPLE'S DEMO-
LA CRATIC REPUBLIC
LATVIA LV
LEBANON LB
LESOTHO LS
LIBERIA LR
LIBYAN ARAB JAMA-
LY HIRIYA
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA, THE
MK FORMER YUGOSLAV REPUBLIC OF
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
38 October 2009 Mobile Checkout Developer Guide
Country Code
Country Codes
B
MICRONESIA, FEDER-
FM ATE D S TAT E S OF
MOLDOVA, REPUBLIC OFMD
MONACO MC
MONGOLIA MN
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
MYANMAR MM
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NETHERLANDS ANTI-
AN LLES
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA
MP ISLANDS
NORWAY NO
OMAN OM
PAKISTAN PK
Mobile Checkout Developer Guide October 2009 39
Country Codes
B
Country Code
PAL AU PW
PALESTINIAN TERRI-
PS TORY, OCCUPIED
PAN AM A PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND
KN NEVIS
SAINT LUCIA LC
SAINT PIERRE AND
PM MIQUELON
SAINT VINCENT AND
VC THE GRENADINES
SAMOA WS
SAN MARINO SM
40 October 2009 Mobile Checkout Developer Guide
Country Code
Country Codes
B
SAO TOME AND PRINC-
ST IPE
SAUDI ARABIA SA
SENEGAL SN
SERBIA AND MON-
CS TENEGRO
SEYCHELLES SC
SIERRA LEONE SL
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH GEORGIA AND
GS THE SOUTH SANDWICH ISLANDS
SPAIN ES
SRI LANKA LK
SUDAN SD
SURINAME SR
SVALBARD AND JAN
SJ MAYEN
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
SYRIAN ARAB REPUB-
SY LIC
Mobile Checkout Developer Guide October 2009 41
Country Codes
B
Country Code
TAIWAN, PROVINCE OF
TW CHINA
TAJIKISTAN TJ
TANZANIA, UNITED
TZ REPUBLIC OF
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND
TT TOBAGO
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS
TC ISLANDS
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIR-
AE AT E S
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR
UM OUTLYING ISLANDS
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
42 October 2009 Mobile Checkout Developer Guide
Country Code
VENEZUELA VE
VIET NAM VN
Country Codes
B
VIRGIN ISLANDS, BRIT-
VG ISH
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW
Mobile Checkout Developer Guide October 2009 43
Country Codes
B
44 October 2009 Mobile Checkout Developer Guide
Loading...