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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
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.
1 PayPal Mobile Checkout Overview 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.
PayPal Mobile Checkout Overview Customer Activation for Mobile Checkout 1 FIGURE 1.1 Activated Mobile Checkout Flow FIGURE 1.
1 PayPal Mobile Checkout Overview 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.
PayPal Mobile Checkout Overview Mobile Checkout Processing Flow 1 Figure 1.3, “Mobile Checkout Processing Flow,” illustrates the processing flow for a Mobile Checkout Transaction. FIGURE 1.
1 PayPal Mobile Checkout Overview 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.
PayPal Mobile Checkout Overview Merchant Integration Points 1 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 O T E : If you do not call DoMobileCheckoutPayment, the transaction is not completed. The token returned by SetMobileCheckout times out after 24 hours.
1 14 PayPal Mobile Checkout Overview Merchant Integration Points October 2009 Mobile Checkout Developer Guide
2 Mobile Checkout API Reference 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.
2 Mobile Checkout API Reference SetMobileCheckout TABLE 2.1 SetMobileCheckout Request SOAP NVP Description Data Type Req? BuyerPhone. PhoneNumber 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 xs:string No ItemAmount AMT Cost of item before tax and shipping.
Mobile Checkout API Reference SetMobileCheckout 2 TABLE 2.1 SetMobileCheckout Request SOAP NVP Description Data Type Req? 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).
2 Mobile Checkout API Reference SetMobileCheckout TABLE 2.1 SetMobileCheckout Request SOAP NVP Description Data Type Req? Address Display Options ADDRESS DISPLAY 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.
Mobile Checkout API Reference SetMobileCheckout 2 TABLE 2.2 Ship To Address Fields SOAP NVP Description Data Type Required Name SHIPTO NAME Person’s name associated with this shipping address. Character length and limitations: 32 single-byte characters xs:string No Street1 SHIPTO STREET Street address line 1. Character length and limitations: 300 single-byte characters xs:string Yes Street2 SHIPTO STREET2 Street address line 2.
2 Mobile Checkout API Reference 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.
Mobile Checkout API Reference DoMobileCheckoutPayment 2 TABLE 2.5 DoMobileCheckoutPayment Response SOAP NVP Description Data Type PaymentInfo See Information about the payment. See Table 2.6 on page 21. ebl:PaymentInfo Type Table 2.6 on page 21 TABLE 2.6 DoMobileCheckoutPayment Response: PaymentInfo Type SOAP NVP Description Data Type TransactionID TRANSACTIONID Unique transaction ID of the payment.
2 Mobile Checkout API Reference DoMobileCheckoutPayment TABLE 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 (.
Mobile Checkout API Reference DoMobileCheckoutPayment 2 TABLE 2.6 DoMobileCheckoutPayment Response: PaymentInfo Type SOAP NVP Description Data Type 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.
2 Mobile Checkout API Reference 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. ns:EmailAddressType PayerID PAYERID Unique PayPal customer account number. Character length and limitations: 17 single-byte characters. ns:UserIDType PayerStatus PAYERSTATUS Status of the payer’s email address.
Mobile Checkout API Reference DoMobileCheckoutPayment 2 TABLE 2.9 DoMobileCheckoutPayment Response: Address Type SOAP NVP Description Data Type Name NAME Person’s name associated with shipping address. Character length and limitations: 32 single-byte characters xs:string Street1 SHIPTO STREET Street address line 1. Character length and limitations: 300 single-byte characters xs:string Street2 SHIPTO STREET2 Street address line 2.
2 Mobile Checkout API Reference 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 26 Error Code Short Message Long Message Description 10001 Internal Error Internal Error Internal API Error. 10800 Internal Error Internal Error Mobile Checkout Internal Error.
Mobile Checkout API Reference Error Codes 2 TABLE 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. 10825 BuyerPhone is not supported by PayPal Mobile. BuyerPhone is not supported by PayPal Mobile. Phone is valid but is not supported by PayPal Mobile (such as a country where the service is not yet available.
2 Mobile Checkout API Reference Error Codes TABLE 2.11 General API Errors Error Code 28 Short Message Long Message Correcting This Error This error can be caused by 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.
Mobile Checkout API Reference Error Codes 2 TABLE 2.
2 30 Mobile Checkout API Reference Error Codes 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 BRL N O T E : This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.
A PayPal Supported Currencies TABLE A.1 PayPal-Supported Currencies and Currency Codes 32 Currency Currency Code Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB U.S.
B Country Codes N O T E : This table lists country codes defined by ISO 3166-1.
B 34 Country Codes Country Code BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM BHUTAN BT BOLIVIA BO BOSNIA AND HERZEGOVINA BA BOTSWANA BW BOUVET ISLAND BV BRAZIL BR BRITISH INDIAN OCEAN TERRITORY IO BRUNEI DARUSSALAM BN BULGARIA BG BURKINA FASO BF BURUNDI BI CAMBODIA KH CAMEROON CM CANADA CA CAPE VERDE CV CAYMAN ISLANDS KY CENTRAL AFRICAN REPUBLIC CF CHAD TD CHILE CL CHINA CN October 2009 Mobile Checkout Developer Guide
Country Codes Country Code CHRISTMAS ISLAND CX COCOS (KEELING) ISLANDS CC COLOMBIA CO COMOROS KM CONGO CG CONGO, THE DEMOCRATIC REPUBLIC OF THE CD 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 B 35
B 36 Country Codes Country Code FALKLAND ISLANDS (MALVINAS) FK FAROE ISLANDS FO FIJI FJ FINLAND FI FRANCE FR FRENCH GUIANA GF FRENCH POLYNESIA PF FRENCH SOUTHERN TERRITORIES TF 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 October 2009 Mobile Checkout Developer Guide
Country Codes Country Code HEARD ISLAND AND MCDONALD ISLANDS HM HOLY SEE (VATICAN CITY STATE) VA HONDURAS HN HONG KONG HK HUNGARY HU ICELAND IS INDIA IN INDONESIA ID IRAN, ISLAMIC REPUBLIC OF IR 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 B KOREA, DEMOCRATIC KP PEOPLE'S REPUBLIC OF KOREA, REPUBLIC OF KR KUWAIT KW Mobile Checkout Developer Guide October 2009 37
B 38 Country Codes Country Code KYRGYZSTAN KG LAO PEOPLE'S DEMOCRATIC REPUBLIC LA LATVIA LV LEBANON LB LESOTHO LS LIBERIA LR LIBYAN ARAB JAMAHIRIYA LY LIECHTENSTEIN LI LITHUANIA LT LUXEMBOURG LU MACAO MO MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK 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 October 2009 Mobile Checkout Developer Guide
Country Codes Country Code MICRONESIA, FEDERATED STATES OF FM MOLDOVA, REPUBLIC OF MD MONACO MC MONGOLIA MN MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ MYANMAR MM NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTILLES AN NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF NORTHERN MARIANA ISLANDS MP NORWAY NO OMAN OM PAKISTAN PK Mobile Checkout Developer Guide October 2009 B 39
B 40 Country Codes Country Code PALAU PW PALESTINIAN TERRITORY, OCCUPIED PS PANAMA 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 NEVIS KN SAINT LUCIA LC SAINT PIERRE AND MIQUELON PM SAINT VINCENT AND THE GRENADINES VC SAMOA WS SAN MARINO SM October 2009 Mobile Checkout Developer Guide
Country Codes Country Code SAO TOME AND PRINCIPE ST SAUDI ARABIA SA SENEGAL SN SERBIA AND MONTENEGRO CS SEYCHELLES SC SIERRA LEONE SL SINGAPORE SG SLOVAKIA SK SLOVENIA SI SOLOMON ISLANDS SB SOMALIA SO SOUTH AFRICA ZA SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS SPAIN ES SRI LANKA LK SUDAN SD SURINAME SR SVALBARD AND JAN MAYEN SJ SWAZILAND SZ SWEDEN SE SWITZERLAND CH SYRIAN ARAB REPUBLIC SY Mobile Checkout Developer Guide October 2009 B 41
B 42 Country Codes Country Code TAIWAN, PROVINCE OF CHINA TW TAJIKISTAN TJ TANZANIA, UNITED REPUBLIC OF TZ THAILAND TH TIMOR-LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND TOBAGO TT TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS ISLANDS TC TUVALU TV UGANDA UG UKRAINE UA UNITED ARAB EMIRATES AE UNITED KINGDOM GB UNITED STATES US UNITED STATES MINOR OUTLYING ISLANDS UM URUGUAY UY UZBEKISTAN UZ VANUATU VU October 2009 Mobile Checkout Developer Guide
Country Codes Country Code VENEZUELA VE VIET NAM VN B VIRGIN ISLANDS, BRIT- VG ISH VIRGIN ISLANDS, U.S.
B 44 Country Codes October 2009 Mobile Checkout Developer Guide
