PayPal Mobile Checkout - 2009 Developer's Guide
Contents
1. Currency code for the gross amount For possible values see Appendix A PayPal Supported Currencies NOTE A single field is returned for the currency code for GrossAmount FeeAmount SettleAmount and TaxAmount PayPal fee amount charged for the transaction Character length and limitations No currency symbol Regardless of currency decimal separator is a period and the optional thousands separator is a comma Currency code for the gross amount For possible values see Appendix A PayPal Supported Currencies Amount deposited in your PayPal account after a currency conversion Currency code for the gross amount For possible values see Appendix A PayPal Supported Currencies Tax charged on the transaction Character length and limitations No currency symbol Regardless of currency decimal separator is a period and the optional thousands separator is a comma Currency code for the gross amount For possible values see Appendix A PayPal Supported Currencies Exchange rate if a currency conversion occurred 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 Data Type cc Basic AmountType ns C2. SetMobileCheckout Request TABLE 2 1 SetMobileCheckout Request SOAP NVP Description Data Type Req BuyerPhone PHONE Three digit country code for buyer s phone number ebl Count No CountryCode COUNTRYCODE Character length and limit 3 single byte characters ryCodeTyp Currently only 1 and 44 are supported S Mobile Checkout Developer Guide October 2009 15 Mobile Checkout API Reference SetMobileCheckout TABLE 2 1 SetMobileCheckout Request SOAP BuyerPhone PhoneNumber ItemAmount ItemAmount CurrencyID Tax Shipping ItemName ItemNumber NVP PHONENUM CURRENCY CODE TAXAMT SHIPPINGAMT NUMBER Description 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 Cost of item before tax and shipping 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 NOTE You must also set the ItemAmount CurrencyID field A three character currency code Default USD For allowable values see Appendix A PayPal Supported Currencies Character limit 3 single byte characters Tax on item p
3. H Response Transaction Results Success Failure Mobile Checkout Developer Guide October 2009 11 12 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 The SetMobileCheckoutRequest contains the following information e Shopping cart information including billing tax and shipping amounts and currencies e 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 e 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 SetMobi leCheckout response contains a Token which identifies the transaction at su
4. on page 19 EMAIL Description Indicates whether a shipping address 1s required for the transaction Valid values are e 0 A shipping address is not required Default e 1 shipping address is required If you pass a value for ShippingA ddress that address is displayed NOTE 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 e 0 Phone number not returned Default e 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 NOTE Ifa confirmed address is required by the merchant s profile then only confirmed addresses are displayed 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 PayPal login page Character length and limit 127 single byte alphanumeric characters Data Type xs string xs string ebl Addre ssType ns Emai
5. described herein PayPal Inc reserves the right to make changes to any information herein without further notice Contents Preface 5 This Gude NENNE ee ee An d 5 Intended Audience 5 Revision History u a sso 5 Where to Go for More 5 Chapter 1 PayPal Mobile Checkout Overview 7 Security on the 7 How Mobile Checkout Works 8 AVallablility o 2 a a x ua Reque keg de acum deg Temas dead ge y ere on eg 8 Customer Activation for Mobile Checkout vonvon 8 Mobile Checkout Processing Flow 2 es 10 Merchant Integration 5 12 Initiating the 12 Redirecting to PayPal Mobile 12 Completing the Transaction e se sa es eado adara 13 Chapter 2 Mobile Checkout API Reference 15 SetMobileCheckout 15 SetMobileCheckout Request 15 SetMobileCheckout Response 19 DoMobileCheckoutPayment ls 20 DoMobileCheckoutPayment Request 20 DoMobileCheckoutPayment Res
6. 2 SHIPTO Street address line 2 xs string STREET2 Character length and limitations 300 single byte characters CityName SHIPTO Name of city xs string CITY Character length and limitations 120 single byte characters StateOr SHIPTO Name of state or province xs string Province STATE Character length and limitations 120 single byte characters Country SHIPTO ISO 3166 country code ns Country COUNTRY For possible values see Appendix B Country CodeType Codes Character length and limitations Two single byte characters PostalCode SHIPTOZIP U S Zip code or other country specific postal code xs string Character length and limitations 20 single byte characters Phone SHIPTOPHONE Phone number associated with this address NUM Address ADDRESS eBay company that maintains this address eBay or ebl AddressOw Owner OWNER PayPal nerTypeCode Address ADDRESS Status of the address on file with PayPal ebl AddressSt Status STATUS None atusCodeType Confirmed Unconfirmed Mobile Checkout Developer Guide October 2009 25 26 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 e Mobile Checkout Error Codes e General API Errors TABLE 2 10 Mobile Checkout Error Codes Error Code 10001 10800 10801 10802 10806 10808 10809 10810 10811 10812 10813 10814 10815 10823 Short
7. AN ARAB JAMA HIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO Code KG LA LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT October 2009 Mobile Checkout Developer Guide Country Codes Country Code MICRONESIA FEDER FM ATED STATES OF MOLDOVA REPUBLIC MD OF MONACO MC MONGOLIA MN MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ MYANMAR MM NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTI LLES NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF NORTHERN MARIANA ISLANDS NORWAY NO OMAN OM PAKISTAN PK Mobile Checkout Developer Guide October 2009 39 B Country Codes 40 Country PALAU PALESTINIAN TERRI TORY OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO Code PW PS PA PG PY PE PH PN PL PR QA RO RU RW SH LC PM WS SM October 2009 Mobile Checkout Developer Guide Country Codes Country Code SAO TOME AND PRINC ST I
8. GO 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 B Country Codes 36 Country FALKLAND ISLANDS MALVINAS FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY GUINEA GUINEA BISSAU GUYANA HAITI Code FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GG GN GW GY HT October 2009 Mobile Checkout Developer Guide Country Codes Country Code 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 B Country Codes 38 Country KYRGYZSTAN LAO PEOPLE S DEMO CRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBY
9. Item L Cheese pizza includes tax gt 14085551234 Total 12 00 USD delivered shortly Pay with PayPal Mobile PIN amp Shipping Home 529 Taylor Ct nn change Payment from Password login pank gt SER Password login Forgot your PIN ehanas Cancel payment Cancel payment FIGURE 1 2 Non Activated Mobile Checkout Flow Merchant Logo PayPal PayPal Merchant Logo Item Cheese Pizza L Log in to pay 12 00 Log in faster Your order has been Price 12 00 Email address Save time by eie a completed and will be A 1 PIN to use instea your includes tax I email and password delivered shortly Pay with PayPal Password 8 Mobile number Home Mobile PIN IPIN login 4 8 numbers No PayPal account Cancel payment Review payment To Merchant Name Item L Cheese pizza Total 12 00 USD Shipping 529 Taylor Ct PayPal Text Message change To activate your phone Payment from please reply with pia Bank x2478 This is a one time change confirmation code and Mobile Checkout Developer Guide October 2009 does not replace your PIN Cancel payment 10 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 1 Mobile Checkout Pro
10. Message Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error AddressDisplayOptions must be 1 because your payment receiving preferences require the buyer to choose a confirmed Internal Error Internal Error Long Message Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error Internal Error AddressDisplayOptions must be 1 because your payment receiving preferences require the buyer to choose a confirmed Internal Error Internal Error Description Internal API Error Mobile Checkout Internal Error Account is locked or restricted System is unavailable Problem completing payment No funding source available to complete the request Invalid recipient email phone Cannot send a payment to yourself Recipient cannot receive payments Problem completing payment No funds held in recipient s preferred currency Recipient does not have a confirmed address For SetMobileCheckout either specify AddressDisplayOption 1 or change payment receiving preferences to not require a confirmed address Recipient s payment receiving preferences do not allow this transaction Attempted to share address or phone to an unregistered phone or email which is not allo
11. PE 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 SRILANKA 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 B Country Codes Country Code TAIWAN PROVINCEOF 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 ATES 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 Codes Country Code VENEZUELA VE VIET NAM VN VIRGIN ISLANDS BRIT VG ISH VIRGIN ISLANDS U S VI WALLIS AND FUTUNA WESTERN SAHARA EH YEMEN YE ZAMBIA ZM ZIMBABWE ZW Mobile Checkout Developer Guide October 2009 43 mx Country Codes 44 October 2009 Mobile Checkout Developer Guide
12. PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Mobile Checkout Developer Guide October 2009 A PayPal Supported Currencies TABLE 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 Country Codes Norte This table lists country codes defined by ISO 3166 1 Table 1 Country Codes Country Code AFGHANISTAN AF LAND ISLANDS AX ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGOLA AO ANGUILLA AI ANTARCTICA AQ ANTIGUA AND BAR AG BUDA ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD BARBADOS BB Mobile Checkout Developer Guide October 2009 B Country Codes 34 Country BELARUS BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZE GOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA Code BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI CM CA CV KY CF TD CL CN October 2009 Mobile Checkout Developer Guide Country Codes Country Code CHRISTMAS ISLAND CX COCOS KEELING CC ISLANDS COLOMBIA CO COMOROS KM CON
13. PayPal Mobile Checkout Developer Guide Last updated October 2009 Mobile Checkout Developer Guide Document Number 10044 en US 200910 O 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 O 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
14. al 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 PayPal Mobile Checkout Overview Customer Activation for Mobile Checkout FIGURE 1 1 Activated Mobile Checkout Flow Merchant Logo PayPal PayPal Merchant Logo Item Cheese Pizza L Log in to pay 12 00 Review payment Your order has been Price 12 00 Mobile number To MM Name completed and will be mo
15. ber 2009 Mobile Checkout Developer Guide PayPal Mobile Checkout Overview PayPal Mobile Checkout provides merchants with the essential components necessary for mobile commerce e hosted quick buyer flow e straightforward merchant interface e Transaction completion data e 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 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 e WAP 2 0 phones not WAP 1 0 e xHTML or HTML markup language e SSL connections e Cookies enabled e No carrier WAP gap If a device or connection fails any of the these check
16. bsequent integration points The token times out after 24 hours Redirecting to PayPal Mobile Checkout After the response from SetMobi leCheckout you must redirect the customer s browser to PayPal The SetMobi leCheckout 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 Q234AD23AF9282 1 Nore 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 October 2009 Mobile Checkout Developer Guide PayPal Mobile Checkout Overview Merchant Integration Points 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 Nore If you do not call DoMobileCheckoutPayment the transaction is not completed The token returned by SetMob
17. cessing Flow Customer Selects product from merchant mobile site website client or SMS keyword list 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 Merchant PayPal Displays product details and gives customer the option to pay with PayPal 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 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 r Request v gt x n Checkout with SetMobileCheckout PayPal PayPal API Server 4 Response Token PayPal Login L HTTP Redirect G gt https mobile paypal com wc t lt Token gt HTTP Redirect Confirm Details ReturnURL Token e Continue a Confirm funding Merchant Confi jon P source and address Thank Request Final Transaction Details You 3 DoMobileCheckoutPayment
18. characters Mobile Checkout Developer Guide October 2009 19 20 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 Token TOKEN Description A timestamped token that uniquely identifies this transaction Use the token returned in SetMobi leCheckout response NOTE The token returned by SetMobileCheckout expires after 24 hours Character length and limitations 20 single byte characters Data Type Required xs string Yes DoMobileCheckoutPayment Response TABLE 2 5 DoMobileCheckoutPayment Response SOAP Custom InvoiceID PayerInfo NVP CUSTOM INVNUM See Table 2 7 on page 24 Description 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 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 byt
19. e alphanumeric characters Information about the customer See Table 2 7 on page 24 Data Type xs string xs string ebl PayerInfo Type October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference FERAI DoMobileCheckoutPayment TABLE 2 5 DoMobileCheckoutPayment Response SOAP NVP Description Data Type PaymentInfo See Information about the payment See Table 2 6 on ebl PaymentInfo Table 2 6 page 21 Type on page 21 TABLE 2 6 DoMobileCheckoutPayment Response Paymentinfo Type SOAP NVP Description Data Type TransactionID TRANSACTIONID Unique transaction ID of the payment xs string Character length and limitations 19 single byte characters Parent PARENT Parent or related transaction identification number This xs string TransactionID TRANSACTIONID field is populated for the following transaction types e Reversal e Capture of an authorized transaction e Reauthorization of a transaction e Capture of an order The value of ParentTransactionID is the original OrderID e Authorization of an order The value of ParentTransactionID is the original OrderID e Capture of an order authorization e 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 ReceiptID RECEIPTID Receipt identification number xs string Character length and limits 16 digits in xxxxxxxx Xxxx xxxx
20. er 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 lt Token gt 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 NOTE PayPal recommends that the URL be the final review page on which the customer confirms the order and payment Character length and limitations no limit 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 IMPORTANT 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 NOTE PayPal recommends that the value be the original page on which the customer chose to pay with PayPal Character length and limitations no limit Data Type Req xs string No xs string No xs string Yes xs string No Mobile Checkout Developer Guide October 2009 17 18 Mobile Checkout API Reference SetMobileCheckout TABLE 2 1 SetMobileCheckout Request SOAP Address Display Options SharePhone ShipTo Address BuyerEmail NVP ADDRESS DISPLAY SHARE PHONENUM See Table 2 2
21. format Transaction TRANSACTION The type of transaction The transaction type for mobile ns Payment Type TYPE payments is send money as if the customer created Transaction the transaction from the PayPal website CodeType PaymentType PAYMENTTYPE Indicates whether the payment is instant or delayed ns Payment Possible values are CodeType e none e instant 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 DoMobileCheckoutPayment TABLE 2 6 DoMobileCheckoutPayment Response Paymentinfo Type SOAP GrossAmount GrossAmount Currency FeeAmount FeeAmount Currency SettleAmount SettleAmount Currency TaxAmount TaxAmount Cur rency ExchangeRate NVP AMT CURRENCYCOD CURRENCYCOD SETTLEAMT Q G Z 1 ENCYCOD TAXAMT J CURRENCYCOD EXCHANGERATE Description 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
22. ileCheckout 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 e Customer information including name shipping address and e mail e Payment information PayerInfo type including billing tax and shipping amounts and other transaction information Mobile Checkout Developer Guide October 2009 13 m PayPal Mobile Checkout Overview Merchant Integration Points 14 October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference This chapter provides detailed specifications for the request and response fields for the following Mobile Checkout APIs e SetMobileCheckout e 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 Nore 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
23. lA ddressTyp e Req No October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference PERI SetMobileCheckout TABLE 2 2 Ship To Address Fields SOAP NVP Description Data Type Required Name SHIPTO Person s name associated with this shipping xs string No NAME address Character length and limitations 32 single byte characters Streetl SHIPTO Street address line 1 xs string Yes STREET Character length and limitations 300 single byte characters Street2 SHIPTO Street address line 2 xs string No STREET2 Character length and limitations 300 single byte characters CityName SHIPTO Name of city xs string Yes CITY Character length and limitations 120 single byte characters StateOr SHIPTO State or province xs string No Province STATE Character length and limitations 120 single byte characters Country SHIPTO ISO 3166 country code ns Country Yes COUNTRY Forallowable values see Appendix B Country CodeType Codes Character limit 2 single byte characters PostalCode SHIPTO U S ZIP code or other country specific postal xs string No ZIP code Character length and limitations 20 single byte characters SetMobileCheckout Response TABLE 2 3 SetMobileCheckout Response SOAP NVP Description Data Type Token TOKEN A timestamped token that uniquely identifies this transaction xs string NOTE The token expires after 24 hours Character length and limitations 20 single byte
24. ng address Invalid phone number Duplicate invoice number Specified token does not belong to the merchant making this API call Payments to this merchant are not available from the country where the buyer account is registered 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 28 Mobile Checkout API Reference Error Codes TABLE 2 11 General API Errors Short Error Code Message Long Message Correcting This Error 10002 Authentication Username Password is incorrect This error can be caused by Authorization an incorrect API username Failed 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 You do not have permissions to make this API Authorization call Failed 10002 Authentication Account is locked or inactive Authorization Failed 10002 Internal Error Internal Error 10002 Authentication Internal Error Authorization Failed 10002 Authentication Account is not verified Authorization Failed 10002 Authentication This call is not defined in the database Authorization Failed 10002 Authentication Token is not valid Authorization Failed 10002 Restricted Account is restricted Your PayPal me
25. ou must manually accept or deny this payment e verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment e unilateral The payment is pending because it was made to an email address that is not yet registered or confirmed e 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 e other The payment is pending for a reason other than those listed above For more information contact PayPal customer service ReasonCode REASONCODE The reason for a reversal if PaymentStatus is ns Reversal reversed This field is always empty for Mobile ReasonCode Checkout Type October 2009 23 Mobile Checkout Developer Guide 24 Mobile Checkout API Reference DoMobileCheckoutPayment TABLE 2 7 DoMobileCheckoutPayment Response Payerinfo Type SOAP NVP Description Data Type Payer EMAIL Payer s e mail address ns EmailAddressType Character length and limitations 127 single byte characters PayerID PAYERID Unique PayPal customer account ns UserIDType number Character length and limitations 17 single byte characters PayerStatus PAYERSTATUS Status of the payer s email address ns PayPalUserStatusCodeType Pa
26. ponse 20 Error CodeS ata bee dom RR RR dod Eo Rede G E Xo UR ud 26 Appendix A PayPal Supported Currencies 31 Appendix B Country Codes 3 Mobile Checkout Developer Guide October 2009 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 e Added information about secure Return and Cancel URLs e Noted that PIN is recommended but not required May 2007 Initial version of document Where to Go for More Information This guide relies on information in the following guides and references e Express Checkout Integration Guide e Name Value Pair API Developer Guide e SOAP API Developer Reference e Sandbox User Guide Mobile Checkout Developer Guide October 2009 Octo
27. rchant account account has been restricted Contact your PayPal account manager for resolution 10002 Authentication Token is not valid Authorization Failed 10002 Authentication API access is disabled for this account Authorization Failed October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference FERAI Error Codes TABLE 2 11 General API Errors Short Error Code Message Long Message Correcting This Error 10002 Authentication Client certificate is disabled Authorization Failed 10002 Restricted Account is restricted account Mobile Checkout Developer Guide October 2009 29 Mobile Checkout Reference Error Codes 30 October 2009 Mobile Checkout Developer Guide 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 NOTE 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 MYR NOTE This currency is supported as a payment currency and a currency balance for in country PayPal accounts only Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso
28. s the customer will not be able to connect to the PayPal servers Norte 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 E 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 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 PayP
29. urchased NOTE The tax amount must be in the same currency as the ItemAmount The shipping costs for this transaction NOTE The shipping amount must be in the same currency as the TtemAmount Character length and limitations The name of the item being ordered Character length and limitations 127 single byte characters Pass through field allowing you to specify details such as SKU Character length and limitations 127 single byte characters Data Type xs string cc Basic AmountTyp e ns Curren cyCodeTyp e cc Basic AmountTyp e cc Basic AmountTyp e xs string xs string Req No Yes 16 October 2009 Mobile Checkout Developer Guide Mobile Checkout Reference TABLE 2 1 SetMobileCheckout Request SetMobileCheckout PERRA SOAP NVP Custom CUSTOM InvoiceID INVNUM ReturnURL RETURNURL CancelURL CANCELURL Description 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 Your own invoice number or ID used to identify the transaction Character length and limitations 127 single byte alphanumeric characters The custom
30. urrency CodeType cc Basic AmountType ns Currency CodeType cc Basic AmountType ns Currency CodeType cc Basic AmountType ns Currency CodeType xs string October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference FERAI DoMobileCheckoutPayment TABLE 2 6 DoMobileCheckoutPayment Response Paymentinfo Type SOAP NVP Description Data Type PaymentStatus PAYMENTSTATUS Status of a PayPal payment ns Payment Status of the payment StatusCode e Completed The payment has been completed Type and the funds have been added successfully to your account balance e Pending The payment is pending See the PendingReason element for more information PendingReason PENDINGREASON The reason the payment is pending e none No pending reason e 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 e 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 e 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 Y
31. wed October 2009 Mobile Checkout Developer Guide Mobile Checkout Reference TABLE 2 10 Mobile Checkout Error Codes Error Codes Error Code 10824 10825 10826 10827 10828 10829 10830 10831 10833 10834 10835 10836 Short Message Internal Error BuyerPhone is not supported by PayPal Mobile Internal Error Internal Error Internal Error ShipToA ddress 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 Internal Error Internal Error Internal Error Long Message Internal Error BuyerPhone is not supported by PayPal Mobile Internal Error Internal Error Internal Error 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 Internal Error Internal Error Internal Error Description All specified amounts must have the same currency Phone is valid but is not supported by PayPal Mobile such as a country where the service is not yet available Checkout session not completed by the buyer Invalid token Token has expired Ship To address ignored Invalid shippi
32. yerName See Table 2 8 Payer s name See Table 2 8 on bl PayerNameTyp on page 24 page 24 PayerCountry COUNTRYCODE Payer s country code ns CountryCodeType For possible values see Appendix B Country Codes Character length and limitations 2 single byte characters PayerBusiness BUSINESS Payer s business name xs string Character length and limitations 127 single byte characters Address See Table 2 9 Payer s address See Table 2 9 on ebl1 AddressType on page 25 page 25 ContactPhone Phone number shared by the xs string customer with the merchant TABLE 2 8 DoMobileCheckoutPayment Response PayerName Type SOAP NVP Description Data Type ebl SALUTATION Payer s salutation ns Salutation Salutation Type ebl First FIRSTNAME Payer s first name ns NameType Name ebl Middle MIDDLENAME Payer s middle name ns NameType Name ebl Last LASTNAME Payer s last name ns NameType Name ebl Suffix SUFFIX Payer s suffix ns SuffixType October 2009 Mobile Checkout Developer Guide Mobile Checkout API Reference a DoMobileCheckoutPayment TABLE 2 9 DoMobileCheckoutPayment Response Address Type SOAP NVP Description Data Type Name NAME Person s name associated with shipping address xs string Character length and limitations 32 single byte characters Streetl SHIPTO Street address line 1 xs string STREET Character length and limitations 300 single byte characters Street
Download Pdf Manuals
Related Search