Home

PayPal Express Checkout - 2013 Payflow Pro Guide

1. 51 Link Your Payflow Account the 51 4 Express Checkout for Payflow Contents Testing Your Integration Using the PayPal Simulator 52 Appendix A Express Checkout Parameter Reference 53 Connection Parameter 53 User Parameter Descriptions 54 Express Checkout Parameter Descriptions 55 Set Express Checkout Request Parameter Descriptions 55 Set Express Checkout Response Parameter Descriptions 61 Get Express Checkout Details Request Parameter Descriptions 62 Get Express Checkout Details Response Parameter Descriptions 62 Do Express Checkout Payment Request Parameter Descriptions 66 Do Express Checkout Payment Response Parameter Descriptions 70 Do Authorization Parameter Descriptions 72 Do Reauthorization Parameter 73 Void Parameter 73 Credit Parameter 74 Delayed Capture Parameter lt 75 Billing Agreement Parameter 76 Create Customer Billing Agreement Request Paramet
2. PAYERID Description Required How you want to obtain payment e Aindicates that this payment is an Authorization subject to settlement with the Delayed Capture request e Oindicates that this payment is an Order subject to settlement with the Delayed Capture request e Sindicates that this is a final Sale for which you are requesting payment NorE You cannot set this value to S in the Set Express Checkout request and then change this value to A on the final Do Express Checkout Payment request Limitations One alpha character Required The tender type method of payment It is always P Limitations One alpha character Required The timestamped token that was returned in the Set Express Checkout response Limitations 20 character string Required Is D to indicate this is a Set Express Checkout request Limitations One alpha character Required Unique PayPal buyer account identification number as returned by Get Express Checkout Details response This value is returned in the URL when the buyer is redirected to your website Limitations 13 character string Express Checkout for Payflow Express Checkout Parameter Reference A Express Checkout Parameter Descriptions TABLE A 7 Do Express Checkout Payment request parameters Parameter Description AMT Required Amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount t
3. be 20 35 Do 36 Do 525254445984 R SUQ 4 SUR ee 37 Delayed Capture 37 Complete 38 Partial us EWA Oe EY BOE ana g W YS 38 OIG 39 Credits 225 bbe ee kus Q kha 40 39 Chapter 4 41 Response 41 Address Verification Service Responses From 42 Card Security Code Results 0 43 Normalized Results 43 PayPal Card Security Code lt 44 PNREF Walle 2 45 acd wt aia Moe a Meek W we ack Grae 44 PNREF Format 5 5542 oe NE ae as UQ 44 RESULT Values RESPMSG 45 RESULT Values for Transaction Declines or 45 Chapter 5 Express Checkout Testing 1 Testing Your Integration Using the 5 51 Create A Business 51 Create a Payflow Test
4. F Response Transaction Results Success Failure The figure shows a typical set of web pages representing a merchant s website The web page layout may differ somewhat from your own web design The buyer uses the PayPal logo to choose PayPal as their method of payment Express Checkout gives you the flexibility to place the PayPal logo at two points in the checkout flow e On your Shopping Cart page at the start of checkout as shown e On your Payment Methods page with other billing options The numbered callouts in the figure correspond to the numbered events described below 10 Express Checkout for Payflow Express Checkout Processing Flow Express Checkout Flow 1 On your website your buyer checks out either by clicking the Check out with PayPal button from your Shopping Cart page as shown in the figure layout or by selecting PayPal from your Payment Methods page This buyer action triggers the call to the Set Express Checkout request 2 server responds to the request by returning a token or string value to your website In the figure above the token is represented by an orange donut The token keeps track of your buyer throughout the checkout process 3 You direct your buyer to the PayPal site where they log in select a funding source and confirm contact and shipping information Express Checkout includes parameters that you can use to customize the PayPal pages so they match characteristics of
5. By clicking Agree and Continue authorize Miata Auto Service to charge my PayPal account for current and future payments based on my relationship with the merchant PayPal will not share my financial information with this merchant How to cancel Credit Card Visa 0276 This credit card transaction will appear on your bill as MIATAAUTOSE Change PayPal Plus Credit Card Fm Receive extended protection on purchases made via PayPal See eligibilty pa Shipping Address 111 Street address Santa Clara CA 950501 United States Chanqe Contact Information uspersonal paypal com Agree and Continue Return to Miata Auto Service PayPal p privacy and security For me yreement and Privacy Policy 4 PayPal redirects the buyer s browser to your return page 5 Call the Get Express Checkout Details request ACTION G to obtain information about the buyer and the buyer s checkout status PayPal returns checkout details including whether the billing agreement was accepted 6 Call the Do Express Checkout Payment request ACTION D to complete the purchase 7 PayPal returns information about the purchase If the required billing agreement information was passed PayPal returns a BAID Save the BAID to implement Payflow reference transactions Express Checkout for Payflow 23 27 Billing Agreements and Reference Transactions Obtaining the BAID With Express Checkout Purchase Example of Obtaini
6. Redirect RetumURL Token G mam 5 Confirm Order Request Token Get Express Checkout Details Server ACTION Response 6 Request Final Transaction Details T API Thank Create Customer Billing Agreement Server You 00 ACTION X 7 amp Response Results BAID The message flow consists of the following comments which correspond to the circled numbers in Figure 2 1 The comments pertain specifically to setting up a billing agreement and obtaining a BAID 1 When the buyer chooses to set up a billing agreement call the Set Express Checkout request ACTION S and pass information about the agreement The billing type required A description of the goods or services associated with the agreement optional The type of PayPal payment you require optional string for your use in any way optional Note Even though the buyer is not making a purchase in this flow provide a value for AMT for example AMT 0 00 2 PayPal returns a TOKEN that you use in subsequent steps 26 Express Checkout for Payflow Billing Agreements and Reference Transactions Obtaining the BAID Without Express Checkout Purchase 3 Redirect the buyer s browser to PayPal to allow the buyer to log in to PayPal or set up PayPal account After the buyer clicks the PayPal button and you submit the Set Express Checkout request you will want to automatically dir
7. Transaction Responses Card Security Code Results TABLE 4 2 Address Verification Service response value mapping PayPal Processor Address Verification Service Code Meaning AVSADDR AVSZIP N No N N P Postal International Z N Y R Retry X X S Service not Supported X X U Unavailable X X W Whole Zip N Y X Exact Match Y Y Y Yes Y Y Z Zip N Y All other X X Card Security Code Results The CVV2MATCH parameter returns Y N or X The CvV2MATCH parameter returns Y N X or a processor specific response Normalized Results If you submit the transaction request parameter for card security code that is the CVV2 parameter the cardholder s bank returns a normalized Yes No response the CVV2MATCH response parameter as described in the table below TABLE 4 3 CVV2MATCH response values CVV2MATCH Value Description Y The submitted value matches the data on file for the card N The submitted value does not match the data on file for the card X The cardholder s bank does not support this service Express Checkout for Payflow 43 44 Transaction Responses PNREF Value PayPal Card Security Code Results The table below shows the detailed results returned by the PayPal processor for card security codes If you want to obtain the PayPal processor value set the VERBOSITY parameter to MEDIUM The processor value is returned in the PROCCVV2 response parameter TABLE 4 4 Card security code response
8. 64 69 78 83 SHIPTOSTREETparameter 61 64 69 78 82 SHIPTOZIP parameter 61 64 70 79 83 Singapore Dollar 85 STATE parameter 65 storefront testing 52 STREET 65 STREET2 parameter 65 Swedish Krona 85 Swiss Franc 85 ZIP parameter 65 Zloty 85 T Taiwan New Dollar 85 TAXAMT parameter 82 TENDER 66 TENDER parameter 55 62 72 77 testing operation 52 Thai Baht 86 token 22 26 TOKEN parameter 30 56 61 62 66 70 76 77 transaction response PNREF parameter 44 RESPMSG parameter 45 RESULT parameter 45 transactions sale 34 TRXTYPE parameter 28 29 55 62 66 72 73 74 75 76 79 U U S Dollar 86 V values billing type 20 VENDOR parameter 54 Y Yen 85 Express Checkout for Payflow
9. Example Bldg 6 Mail Stop 3 Limitations 30 character string Optional Ship to city Limitations 40 character string Optional Ship to state Limitations 40 character string Optional Ship to postal code Limitations 16 character string Optional Ship to country Limitations Two character country code Set Express Checkout Response Parameter Descriptions TABLE A 4 Set Express Checkout response parameters Parameter TOKEN RESULT RESPMSG Description A time stamped token by which you identify to PayPal that you are processing this payment with Express Checkout The token expires after three hours If you set TOKEN in the Set Express Checkout request the value of TOKEN in the response is identical to the value in the request Limitations 20 character string Response value for the request Response message in case if any error occurs Express Checkout for Payflow 61 Express Checkout Parameter Reference Express Checkout Parameter Descriptions Get Express Checkout Details Request Parameter Descriptions TABLE A 5 Get Express Checkout Details request parameters Parameter Description TRXTYPE Required How you want to obtain payment e Aindicates that this payment is an Authorization subject to settlement with the Delayed Capture request e Oindicates that this payment is an Order subject to settlement with the Delayed Capture request e S indicates that this is final S
10. RESULT 41 45 RETURNURL 13 55 SHIPTOCITY 61 64 69 78 83 SHIPTOCOUNTRY 61 64 70 78 79 83 SHIPTONAME 61 64 69 82 SHIPTOSTATE 61 64 69 79 83 SHIPTOSTREET 61 64 69 78 82 SHIPTOSTREET2 61 64 69 78 83 SHIPTOZIP 61 64 70 79 83 STATE 65 STREET2 65 Express Checkout for Payflow TAXAMT 82 TENDER 55 62 72 77 TOKEN 14 15 56 61 62 66 70 76 77 TRXTYPE 33 44 55 62 66 72 73 74 75 76 79 VENDOR 54 ZIP 65 Payflow parameters ADJUSTMENTAMT 63 Payflow parameters NOTE 63 Payflow Test Account 51 PAYMENTTYPE parameter 57 70 76 80 83 PayPal supported currencies 85 PENDINGREASON parameter 71 Peso 85 Phillippine Peso 85 PHONENUM parameter 64 PNREF 41 format of value 44 PNREF value 44 Polish Zloty 85 Pound Sterling 85 PPREF parameter 42 70 72 73 74 75 76 R Real 85 recurring billing profile 20 Recurring Payments profile 20 RecurringBilling 20 RecurringPayments 20 redirect 23 27 reference transaction parameter descriptions 31 reference transactions 19 REQBILLINGADDRESS parameter 59 REQCONFIRMSHIPPING parameter 80 RESPMSG parameter 42 RESPMSG value 45 RESULT 41 RESULT value 45 RETURNURL parameter 55 RETURNURLparameter 13 Ringgit 85 s sale transaction type 34 SHIPTOCITY parameter 61 64 69 78 83 SHIPTOCOUNTRY parameter 61 64 70 78 79 83 95 96 SHIPTONAME parameter 61 64 69 82 7 SHIPTOSTATE parameter 61 64 69 79 83 SHIPTOSTREET 2 parameter 61
11. Response Parameters When transaction finishes the server returns a response made up of name value pairs For example this is a response to a Sale transaction request RESULT 0 amp PNREF EFHP0D426A53 amp RESPMSG APPROVED amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CVV2MATCH Y amp PPREF 6 8W3371331353001F amp CORRELATIONID 2dc60e253495e Express Checkout transaction responses include the response parameters described below as well as parameters returned by the specific transaction type TRXTYPE and ACTION TABLE 4 1 General response parameters Parameter Description RESULT The outcome of the attempted transaction A result of 0 zero indicates the transaction was approved Any other number indicates a decline or error NOTE The PayPal processor may also return a warning message in the RESPMSG string when RESULT 0 For more information on corrective actions see the PayPal developer documentation on Developer Central Limitations Numeric PNREF Payflow Transaction ID a unique 12 character alphanumeric string that identifies the transaction Express Checkout for Payflow 41 42 Transaction Responses Address Verification Service Responses From PayPal TABLE 4 1 General response parameters Parameter PPREF RESPMSG CORRELATIONID Description Unique PayPal transaction ID of the payment If the request ACTION was A Authorization you should store the value of PPREF if you ne
12. amp FEEAMT 0 33 amp BAID B 12345678901234567 amp PAYMENTTYPE instant amp PENDINGREASON authorization 30 Express Checkout for Payflow Billing Agreements and Reference Transactions 20081 Using Reference Transactions Reference Transaction Request Passing the PNREF Value as ORIGID Request In this example the is not required because the ORIGID is being passed PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION D amp TENDER P amp 1 SORIGID E24P0A03B013 Response RESULT 0 amp PNREF E24P0A03B015 amp RESPMSG Approved amp PPREF 44000000000180907 amp CORRELATIONID dr093d08c9f 01 amp BAID B 12345678901234567 amp PAYMENTTYPE instant amp PENDINGREASON authorization Express Checkout for Payflow 31 ss Billing Agreements and Reference Transactions Using Reference Transactions 32 Express Checkout for Payflow Express Checkout Transaction Types The Payflow gateway supports transaction types TRXTYPE for obtaining payment during the Express Checkout flow as well as for managing the capture of payments after the Express Checkout flow e Honor Period and Authorization Period e Payment Transaction Types e Sale e Authorization e Order e Do Reauthorization e Do Authorization e Delayed Capture e Void e Credit Honor Period and Authorization Period Your business may not be able to provide immediate fulfillment of a product or service
13. 16 character string Optional Bill to country code The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations Four alphanumeric characters Reference Transaction Response Parameters TABLE A 24 Reference Transaction Response Parameters Parameter BAID PAYMENTTYPE Description BAID returned from Create Customer Billing Agreement Limitations 19 character string Returns one of the following values e instantonly The payment is made with no delay e any The payment may be made with no delay or the payment is pending Limitations 11 characters Express Checkout for Payflow 83 Express Checkout Parameter Reference Reference Transaction Parameter Descriptions 84 Express Checkout for Payflow Currency Codes The following currencies are supported for use in transactions TABLE B 1 Currencies and Currency Codes Code Currency AUD Australian Dollar BRL Brazilian Real NOTE Supported as a payment currency and a currency balance for in country PayPal accounts only CAD Canadian Dollar CZK Czech Koruna DKK Danish Krone EUR Euro HKD Hong Kong Dollar HUF Hungarian Forint ILS Israeli New Sheqel JPY Japanese Yen MYR Malaysian Ringgit NOTE Supported as a payment currency and a currency balance for in country PayPal accounts only MXN Mexican Peso NOK Norwegian Krone NZD New Zealand Dollar PHP Phillippin
14. 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Required if L COSTn is supplied Line item unit quantity Limitations 10 character integer Required if L COSTn is specified Sum of cost of all items in this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Express Checkout for Payflow 57 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter TAXAMT FREIGHTAMT HANDLINGAMT DISCOUNT INSURANCEAMT ALLOWNOTE Description Required if TAXAMTn is specified Sum of tax for all items in this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Total shipping cost for this order NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional
15. 95 not 1 199 95 Optional Total handling cost for this order NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Shipping discount for this order Specify the discount as a positive amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Ship to name Limitations 32 character string Optional Ship to street address Limitations 30 character string 82 Express Checkout for Payflow Express Checkout Parameter Reference Reference Transaction Parameter Descriptions TABLE A 23 Reference Transaction Request Parameters Parameter SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOZIP COUNTRYCODE Description Optional Extended Ship to street address Example Bldg 6 Mail Stop 3 Limitations 30 character string Optional Ship to city Limitations 40 character string Optional Ship to state Limitations 40 character string Optional Ship to postal code Limitations
16. An item for example may not be immediately available to ship because it is temporarily out of stock Under these circumstances you can have the buyer approve of placing a 29 day hold or authorization period on their balance for the amount of the authorization to ensure funds are available for capture After a successful authorization PayPal honors the authorized funds for a three day honor period You can extend the honor period once with a Do Reauthorization or multiple times with a Do Authorization Payment Transaction Types During the Express Checkout flow the following transaction types are supported e Sale TRXTYPE S e Authorization TRXTYPE A Order Express Checkout for Payflow 33 34 Express Checkout Transaction Types Sale After the Express Checkout flow you can manage the capture of payment using the following transaction types e Do Reauthorization TRXTYPE A e Do Authorization TRXTYPE A e Delayed Capture TRXTYPE D e Void TRXTYPE V e Credit TRXTYPE C Sale A Sale transaction charges the specified amount against the account and marks the transaction for immediate fund transfer Use a Sale transaction when you can fulfill an order immediately and you know the final amount of the payment at the time you send the Do Express Checkout Payment Details request A Sale is appropriate for example if you have the items in stock for immediate shipment To set up a Sale set these pa
17. Country Codes 90 Country MICRONESIA FEDER ATED STATES OF MOLDOVA REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTI LLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN Code MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK Country PALAU PALESTINIAN 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 Express Checkout for Payflow Code PW PS PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH LC PM VC WS SM Country SAO TOME AND PRINC IPE SAUDI ARABIA SENEGAL SERBIA AND MON TENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOMALIA SOUTH AFRICA SOUTH GEORGIA AND THESOUTHSANDWICH ISLANDS SPAIN SRILANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUB LIC TAIWAN PROVINCE OF CHINA TAJIKISTAN Express Checkout for Payflow Code ST SA SN CS SC SL SG SK SI SB SO ZA GS ES LK SD SR
18. SJ SZ SE CH SY TW TJ Country TANZANIA UNITED REPUBLIC OF THAILAND TIMOR LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE UNITED ARAB EMIR ATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS BRIT ISH Code TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN VG 91 Country Codes 92 Country VIRGIN ISLANDS U S WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE Code VI EH YE ZM ZW Express Checkout for Payflow Index A ACTION parameter 12 55 62 66 76 77 79 ADDROVERRIDE parameter 59 ADJUSTMENTAMT parameter 63 AMT parameter 12 AMTparameter 55 67 72 74 75 81 application testing 52 Australian Dollar 85 AVSADDR parameter 66 BA_CUSTOM parameter 56 77 78 BA_DESC parameter 56 77 78 Baht 86 BAID parameter 23 27 29 30 70 77 78 83 billing agreement message flow when obtaining with purchase 22 26 updating 29 with a customer purchase 21 without a customer purchase 21 billing agreements canceling 29 using with reference transactions 19 billing types 20 BILLINGTYPE parameter 56 BILLTONAME parameter 65 Brazilian Real 85 BUTTONSOURCE parameter 67 80 C Canadian Dollar 85 CANCELURL parameter 13 56 CAPTURECOMPLE
19. Total handling cost for this order NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Shipping discount for this order Specify the discount as a positive amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Total shipping insurance cost for this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Is 1 or 0 default If 1 the buyer may enter a note in the Express Checkout flow to be returned by the responses to Get Express Checkout Details and Do Express Checkout Payment Limitations Numeric 58 Express Checkout for Payflow Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter MAXAMT ORDERDESC CUSTOM INVNUM PHONENUM REQBILLINGADDRESS REQCONFIRMS
20. code mapping PayPal Processor CVV2 PayPal Processor Code Code Description PROCVV2MATCH M Match Y N No Match N P Not Processed x S Service Not Supported X U Unavailable X No Response X All other X PNREF Value The PNRFF is a unique transaction identification number issued by PayPal that identifies the transaction for billing reporting and transaction data purposes The PNREF value appears in the Transaction ID column in PayPal Manager reports e The PNREF value is used as the ORIGID value original transaction ID in Delayed Capture transactions TRXTYPE D Credits TRXTYPE C Inquiries TRXTYPE 1 and Voids TRXTYPE V e The PNREF value is used as the ORIGID value original transaction ID value in reference transactions for Authorization TRXTYPE A and Sale TRXTYPESS Norte The PNREF is also referred to as the Transaction ID in PayPal Manager PNREF Format The PNREF is a 12 character string of printable characters for example e VADE0B248932 e ACRAF23DB3C4 Norte Printable characters also include symbols other than letters and numbers such as the question mark A PNREF typically contains letters and numbers only The PNREF in a transaction response tells you that your transaction is connecting to PayPal Express Checkout for Payflow Transaction Responses RESULT Values and RESPMSG Text RESULT Values and RESPMSG Text The RESULT parameter and value is the first name value pair returned in th
21. currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Buyer s first name Limitations 25 character string Buyer s last name Limitations 25 character string Express Checkout for Payflow 63 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 6 Get Express Checkout Details response parameters Parameter SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOZIP SHI PTOCOUNTRY SHIPTOBUSINESS CUSTOM INVNUM PHONENUM Description Ship to name If you include a shipping address and provide a value for the AddressOverride ADDROVERRIDE parameter PayPal returns this same address in the Get Express Checkout Details response Limitations 32 character string Ship to street address If you include a shipping address and provide a value for the AddressOverride ADDROVERRIDE parameter PayPal returns this same address in the Get Express Checkout Details response Limitations 30 character string Extended Ship to street address Example Bldg 6 Mail Stop 3 Limitations 30 character string Ship to city Limitations 40 character string Ship to state Limitations 40 character string Ship to postal code Limitations 16 character string Ship to country Limitations Two character country code Buyer s busines
22. is passed you also must pass SHIPTOCITY SHIPTOSTATE SHIPTOZIP and SHIPTOCOUNTRY Limitations 30 character string Optional Extended Ship to street address Example Bldg 6 Mail Stop 3 Limitations 30 character string Optional Ship to city If SHIPTOCITY is passed you also must pass SHIPTOSTREET SHIPTOSTATE SHIPTOZIP and SHIPTOCOUNTRY Limitations 40 character string Express Checkout for Payflow Express Checkout Parameter Reference A Reference Transaction Parameter Descriptions TABLE A 22 Update Customer Billing Agreement response parameters Parameter Description SHIPTOSTATE Optional Ship to state If SHIPTOSTATE is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOZIP and SHIPTOCOUNTRY Limitations 40 character string SHIPTOZIP Optional Ship to postal code If SHIPTOZIP is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOSTATE and SHIPTOCOUNTRY Limitations 16 character string SHIPTOCOUNTRY Optional Ship to country If SHIPTOCOUNTRY is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOSTATE and SHIPTOZIP Limitations Two character country code RESULT Response value for the request RESPMSG Response message in case if any error occurs Reference Transaction Parameter Descriptions Reference Transaction Request Parameters TABLE A 23 Reference Transaction Request Parameters Parameter Description ACTION Required Is the valu
23. meet the security settings specified on the PayPal Manager Security Settings page If the transaction exceeded the Maximum Amount security setting then no values are returned for AVS or CSC AVS validation failed The AVS return value should appear in the RESPMSG CSC validation failed The CSC return value should appear in the RESPMSG 118 Invalid keywords found in string fields 120 Attempt to reference a failed transaction 121 Not enabled for feature 122 Merchant sale total will exceed the credit cap with current transaction ACH transactions only 125 Fraud Protection Services Filter Declined by filters 48 Express Checkout for Payflow Transaction Responses RESULT Values and RESPMSG Text TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 126 Fraud Protection Services Filter Flagged for review by filters IMPORTANT RESULT value 126 indicates that a transaction triggered a fraud filter This is not an error but a notice that the transaction is in a review status The transaction has been authorized but requires you to review and to manually accept the transaction before it will be allowed to settle RESULT value 126 is intended to give you an idea of the kind of transaction that is considered suspicious to enable you to evaluate whether you can benefit from using the Fraud Protection Services To eliminate RESULT 126 turn the filters off For more information
24. operation testing 52 ORDERDESC parameter 59 67 80 ORIGID parameter 30 72 73 74 75 P PAGESTYLE parameter 60 PARTNER parameter 54 PAYERID in RETURNURL 15 PAYERID parameter 30 62 66 PAYERSTATUS parameter 63 78 Payflow parameter CURRENCY 55 80 MEMO 75 Payflow parameters ACTION 12 14 15 55 62 66 79 ADDROVERRIDE 59 AMT 12 15 55 67 72 74 75 81 AVSADDR 66 BA_CUSTOM 56 BA_DESC 56 77 78 BAID 70 77 78 83 BILLINGTYPE 56 BILLTONAME 65 BUTTONSOURCE 67 80 CALCELURL 13 CANCELURL 56 CAPTURECOMPLETE 38 76 CITY 65 COLOR 60 CORRELATIONID 42 COUNTRYCODE 65 CUSTIP 79 CUSTOM 59 64 67 80 CVV2MATCH 43 DISCOUNT 63 82 EMAIL 61 62 FEEAMT 71 FIRSTNAME 63 78 FREIGHTAMT 82 HANDLINGAMT 82 HDRBACKCOLOR 60 HDRBORDERCOLOR 60 Express Checkout for Payflow HDRIMG 60 HOSTADDRESS 53 HOSTPORT 53 54 INVNUM 59 64 67 80 ITEMAMT 81 L_BILLINGAGREEMENTDESCRIPTIONn 56 L_BILLINGTYPEn 56 L_COSTn 57 81 L_DESCn_ 57 80 L_NAMEn 57 80 L_QTYn 57 81 L_TAXAMTn 57 68 81 LASTNAME 63 78 LOCALECODE 60 MAXAMT 59 NOSHIPPING 59 NOTE 75 NOTIFYURL 67 80 ORDERDESC 59 67 80 ORIGID 44 72 73 74 75 PAGESTYLE 60 PARMLIST 53 PARTNER 54 PAYERID 15 62 66 PAYERSTATUS 63 78 PAYMENTTYPE 57 70 76 80 83 PENDINGREASON 71 PNREF 41 44 42 70 72 73 74 75 76 PROXYADDRESS 53 54 PROXYLOGON 54 PROXYPASSWORD 54 PROXYPORT 53 REQBILLINGADDRESS 59 REQCONFIRMSHIPPING 80 RESPMSG 42 45
25. or invalid XID in PARES 1051 Buyer Authentication Service Validate Authentication failed Mismatched or invalid order date in PARES 1052 Buyer Authentication Service Validate Authentication failed This PARES was already validated for a previous Validate Authentication transaction 50 Express Checkout for Payflow Express Checkout Testing You can set up the testing of your Integration using two methods e Testing Your Integration Using the Sandbox e Testing Your Integration Using the PayPal Simulator Testing Your Integration Using the Sandbox To set up the testing of your integration using the Sandbox e Create A Business Account e Create a Payflow Test Account e Link Your Payflow Account to the Sandbox Create A Business Account If you do not already have a Payflow account follow the procedure below to create one If your account is already set up proceed to Create a Payflow Test Account on page 51 1 Follow the procedure described on the MTS website https ppmts custhelp com app answers detail a_id 929 Create a Payflow Test Account To create Payflow test account follow the procedure described on the MTS website https ppmts custhelp com app answers detail a_id 929 Link Your Payflow Account to the Sandbox To link your Payflow account to the Sandbox follow the procedure described on the MTS website https ppmts custhelp com app answers detail a_id 929 Be sure to e Send al
26. see the fraud documentation for your payments solution 127 Fraud Protection Services Filter Not processed by filters 128 Fraud Protection Services Filter Declined by merchant after being flagged for review by filters 132 Card has not been submitted for update 133 Data mismatch in HTTP retry request 150 Issuing bank timed out 151 Issuing bank unavailable 200 Reauth error 201 Order error 600 Cybercash Batch Error 601 Cybercash Query Error 1000 Generic host error This is a generic message returned by your credit card processor The RESPMSG will contain more information describing the error 1001 Buyer Authentication Service unavailable 1002 Buyer Authentication Service Transaction timeout 1003 Buyer Authentication Service Invalid client version 1004 Buyer Authentication Service Invalid timeout value 1011 Buyer Authentication Service unavailable 1012 Buyer Authentication Service unavailable 1013 Buyer Authentication Service unavailable 1014 Buyer Authentication Service Merchant is not enrolled for Buyer Authentication Service 3 D Secure Express Checkout for Payflow 49 Transaction Responses RESULT Values and RESPMSG Text TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 1016 Buyer Authentication Service 3 D Secure error response received Instead of receiving a PARes response to a Validate Authentication transaction an error response wa
27. services associated with the billing agreement Limitations 255 character string BA STATUS Optional The status of the billing agreement The only value is cancel Express Checkout for Payflow 77 78 Express Checkout Parameter Reference Billing Agreement Parameter Descriptions Update Customer Billing Agreement Response Parameters TABLE A 22 Update Customer Billing Agreement response parameters Parameter BAID CUSTOM DESC EMAIL PAYERSTATUS PHONENUM FIRSTNAME LASTNAME SHIPTOBUSINESS SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY Description The billing agreement ID Limitations 19 character string Custom annotation field for your exclusive use Limitations 255 character string Description of goods or services associated with the billing agreement Limitations 255 character string Email address of the buyer as entered during checkout Limitations 127 character alphanumeric string Status of buyer Values are e verified e unverified Limitations 10 character string Account holder s telephone number Limitations 20 character string The field mask is US numbers international numbers Buyer s first name Limitations 25 character string Buyer s last name Limitations 25 character string Buyer s business name Limitations 127 character string Optional Ship to street address If SHIPTOSTREET
28. string Express Checkout for Payflow 75 76 Express Checkout Parameter Reference Billing Agreement Parameter Descriptions TABLE A 17 Delayed Capture request parameters Parameter CAPTURECOMPLETE Description Optional Indicates if this Delayed Capture transaction is the last capture you intend to make The values are e y default eN If CAPTURECOMPLETE is Y any remaining amount of the original reauthorized transaction is automatically voided Limitations 12 character alphanumeric string TABLE A 18 Delayed Capture response parameters Parameter PPREF PAYMENTTYPE RESULT RESPMSG Description Unique PayPal transaction ID Limitations 17 character string Type of payment Values are e instantonly The payment is made with no delay e The payment may be made with no delay or the payment is pending Limitations 11 characters Response value for the request Response message in case if any error occurs Billing Agreement Parameter Descriptions Create Customer Billing Agreement Request Parameters TABLE A 19 Create Customer Billing Agreement request parameters Parameter ACTION TOKEN TRXTYPE Description Required Is X to indicate this is a Create Customer Billing Agreement without purchase request Limitations One alpha character Required A time stamped token the value of which was returned in the Set Customer Billing Agreement response L
29. the image you want to appear at the top left of the payment page The image has a maximum size of 750 pixels wide by 90 pixels high PayPal recommends that you provide an image that is stored on a secure https server Limitations 127 character string Optional Sets the border color around the header of the payment page The border is a two pixel perimeter around the header space which is 750 pixels wide by 90 pixels high Limitations Six character HTML hexadecimal color code ASCII Optional Sets the background color for the header of the payment page Limitations Six character HTML hexadecimal color code in ASCII Optional Sets the background color for the payment page Limitations Six character HTML hexadecimal color code in ASCII Express Checkout for Payflow Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter EMAIL SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOZIP SHI PTOCOUNTRY Description Optional Email address of the buyer as entered during checkout PayPal uses this to fill out the PayPal membership sign up portion of the PayPal login page Limitations 127 character alphanumeric string Optional Ship to name Limitations 32 character string Optional Ship to street address Limitations 30 character string Optional Extended Ship to street address
30. the value is A Limitations One alpha character Required The tender type method of payment It is always P Limitations One alpha character Required Payflow transaction ID To authorize an Order set this parameter to the value of the PNREF returned in the Do Express Checkout Payment response when Do Express Checkout Payment request was submitted with TRXTYPE O Limitations 12 case sensitive alphanumeric characters Optional Amount If you do not pass a value for AMT the amount of the original transaction 15 sent the Do Authorization request Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 TABLE A 10 Do Authorization response parameters Parameter PPREF RESULT RESPMSG Description Unique PayPal transaction ID Limitations 17 character string Response value for the request Response message in case if any error occurs 72 Express Checkout for Payflow Express Checkout Parameter Reference Do Reauthorization Parameter Descriptions Do Reauthorization Parameter Descriptions TABLE A 11 Do Reauthorization request parameters Parameter TRXTYPE TENDER ORIGID DOREAUTHORI ZATION Description Required How you want to obtain payment Is A which indicates that this payment is an Authorization
31. your own website For example you can provide your own logo and colors 4 When your buyer clicks the Continue button PayPal sends the buyer back to your site at the return URL you specified in the Set Express Checkout request The token is appended to the URL to identify the buyer 5 Optionally you can send the Get Express Checkout Details request to obtain details about your buyer such as the buyer s telephone number and shipping address You send the token to identify the buyer The server returns the requested information 6 When your buyer clicks the Pay button you send the Do Express Checkout Payment request to perform the actual payment transaction 7 The server returns the transaction result Express Checkout Flow Through a set of name value pair parameters you provide Express Checkout transaction data to the server The server responds with RESULT and RESPMSG values along with other response parameter data about the transaction Unlike most Payflow transactions which consist of a single request call Express Checkout is a three step process where the second step is optional 1 Set Express Checkout sets up the data about the transaction and controls what is displayed to the buyer on the PayPal site when the buyer chooses PayPal at checkout 2 Get Express Checkout Details is an optional request enabling you to obtain information about the transaction for display on your own website 3 Do Express Checkout Paymen
32. 1 amp AMT 34 00 Express Checkout for Payflow Express Checkout Transaction Types Void Void A Void transaction voids any of the following transaction types Order e Authorizations Authorization Do Authorization or Do Reauthorization You can use a Void transaction only transactions that have not yet settled To refund a buyer s money for a settled transaction you must use a Credit transaction If you void an unsettled transaction the full authorized amount of the original transaction becomes void and can no longer be captured Norte As part of its internal process PayPal makes reasonable effort to process authorization reversals for void transactions for debit and credit cards However there is no guarantee authorization reversal requests will be honored To set up a Void transaction you must pass the following parameters in the request string e Set ORIGID PNREF PNREF value returned in the response to the original Authorization or Order e Set TRXTYPE V This is an example Void transaction request with the required parameters set TRXTYPE V amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp ORIGID EFHPOCDBF5C7 Credit A Credit transaction refunds the buyer for a settled transaction Credit transactions are permitted only against existing Sale and Delayed Capture transactions To set up a Credit transaction request you must pass the followin
33. D password amp TENDER P amp USER user amp ACTION U DESC Description amp BAID B 92K90916NV400134C amp BA_STATUS cancel Express Checkout for Payflow 29 Billing Agreements and Reference Transactions Using Reference Transactions Response RESULT 0 amp RESPMSG Approved amp PPREF 68W3371331353001F amp CORRELATIONID 6d348905b0d59 amp BAID B 92K90916NV400134C Using Reference Transactions This section provides examples of reference transactions that bill PayPal accounts The examples illustrate two parameter options In the reference transaction request you can pass either of the following name value pair parameters returned in either the response to Create Customer Billing Agreement ACTION X or the response to Do Express Checkout Payment ACTION D e PNREF passed as value of ORIGID e BAID The examples below are based on Do Express Checkout Payment ACTION D and illustrate passing the ORIGID and the BAID The reference transaction request does not pass the Express Checkout TOKEN or PAYERID as described in Express Checkout Processing Flow on page 9 Reference Transaction Request Passing the BAID Request PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION D amp TENDER P SAMT 1 amp BAID B 12345678901234567 Response RESULT 0 amp PNREF E24P0A03B014 amp RESPMSG Approved amp PPREF 44000000000180905 amp CORRELATIONID dr093d08c9f01
34. Field format error Invalid information entered See RESPMSG 8 Not a transaction server 9 Too many parameters or invalid stream 10 Too many line items 11 Client time out waiting for response 12 Declined Check the credit card number expiration date and transaction information to make sure they were entered correctly If this does not resolve the problem have the customer call their card issuing bank to resolve 13 Referral Transaction cannot be approved electronically but can be approved with a verbal authorization Contact your merchant bank to obtain an authorization and submit a manual Voice Authorization transaction 19 Original transaction ID not found The transaction ID you entered for this transaction is not valid See RESPMSG 20 Cannot find the customer reference number 22 Invalid ABA number 23 Invalid account number Check credit card number and re submit 24 Invalid expiration date Check and re submit 25 Invalid Host Mapping You are trying to process a tender type such as Discover Card but you are not set up with your merchant bank to accept this card type e You are trying to process a tender type such as Discover Card but you are not set up with your merchant bank to accept this card type e You are trying to process an Express Checkout transaction when your account is not set up to do so Contact your account holder to have Express Checkout added to your account 46 Express Checkout for Payflow Transaction R
35. HIPPIN G NOSHIPPING ADDROVERRIDE Description Optional The expected maximum total amount of the complete order including shipping and tax charges Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Description of items the buyer is purchasing Limitations 127 character alphanumeric string Optional Free form field for your own use such as a tracking number or other value you want PayPal to return in the Get Express Checkout Details response Limitations 256 character alphanumeric string Optional Merchant invoice number If you do not provide an invoice number the transaction ID PNREF will be submitted Limitations Nine character alphanumeric string Account holder s telephone number Limitations 20 character string The field mask is US numbers international numbers Optional Is 1 or 0 The value 1 indicates that you require that the buyer s billing address on file with PayPal be returned Setting this element will return BILLTONAME STREET STREET2 CITY STATE ZIP and COUNTRYCODE Limitations One character Optional Is 1 or 0 The value 1 indicates that you require that the buyer s shipping address on file with PayPal be a confirmed address Setting this e
36. HIPTOCOUNTRY Limitations 40 character string Express Checkout for Payflow 69 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 7 Do Express Checkout Payment request parameters Parameter SHIPTOZIP SHI PTOCOUNTRY PHONENUM Description Optional Ship to postal code If SHIPTOZIP is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOSTATE and SHIPTOCOUNTRY Limitations 16 character string Optional Ship to country If SHIPTOCOUNTRY is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOSTATE and SHIPTOZIP Limitations Two character country code Optional Account holder s telephone number Limitations 20 character string The field mask is US numbers international numbers Do Express Checkout Payment Response Parameter Descriptions TABLE A 8 Do Express Checkout Payment response parameters Parameter TOKEN PPREF BAID PAYMENTTYPE Description The timestamped token that was returned in the Set Express Checkout response Limitations 20 character string Unique PayPal transaction ID If the request ACTION was A Authorization you should store the value of PPREF if you need to research a specific transaction with PayPal Limitations 17 character string The billing agreement ID is returned if BILLINGTYPE is passed in the Set Express Checkout request to set up a
37. ME Smith amp SHIPTONAME Joe Smith amp SHIPTOSTREET 111 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOZIP 95100 amp SHIPTOCOUNTRY US Do Express Checkout Payment Request ACTION D PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION D amp TENDER P amp AMT 10 00 amp TOKEN EC 36X58962RS656712N amp PAYERID J5MSNK7FP5KA8 Do Express Checkout Payment Response The response returns the BATD RESULT 0 amp PNREF E24P0A03B013 amp RESPMSG Approved amp TOKEN EC 11X52562RT656789N amp PPREF 44000000000180903 amp CORRELATIONID 3a3204997455r amp BAID B 12345678901234567 amp PAYMENTTYPE any amp PENDINGREASON authorization Obtaining the BAID Without Express Checkout Purchase To set up the billing agreement and obtain the BAID without the buyer making an Express Checkout purchase from your website you add one new request to create the billing agreement to your current Express Checkout integration Figure 2 3 summarizes the flow Express Checkout for Payflow 25 je Billing Agreements and Reference Transactions Obtaining the BAID Without Express Checkout Purchase FIGURE 2 3 Obtaining the BAID without Express Checkout purchase Merchant website G Request gt Set Express Checkout API ka i ACTION S BILLINGTYPE MerchantinitiatedBilling Server 2 4 Response Token PayPal Login La 5 G wO
38. META HTTP EQUIV Refresh CONTENT 0 URL https www paypal com cgi bin webscr cmd _express checkout amp token lt TOKEN gt gt lt head gt lt body gt lt Most buyers will see the text below for less than a second gt lt Some browser types example cell phone do not support META refresh tags gt lt a href https www paypal com cgi bin webscr cmd _express checkout amp token lt TOKEN gt Click here if you are not redirected to PayPal within 5 seconds lt a gt lt body gt lt html gt Get Express Checkout Details ACTION G The Get Express Checkout Details request enables you to retrieve the buyer s billing information such as the shipping address and email address If you use Get Express Checkout Details you need to pass data for these parameters e ACTION e TOKEN The following is an example Get Express Checkout Details request TRXTYPE S amp VENDOR vendor amp USER user amp PWD pwd amp TENDER P amp PARTNER partner amp ACTION G amp TOKEN EC 17C76533PL706494P The following is the Get Express Checkout Details response Express Checkout for Payflow Express Checkout Processing Flow i Express Checkout Sale Transaction Example RESULT 0 amp RESPMSG Approved amp AVSADDR Y amp TOKEN EC 17C76533PL706494P amp PAYERID FHY40XY7CV9PG amp EMAIL buyer name aol com amp PAYERSTATUS verified amp FIRSTNAME J amp LASTNAME Smith amp CUSTOM TRVV14459 amp BUSINESS Monr
39. ORIGID PNREF PNREF value returned in original Order response and TRXTYPE A in a Do Authorization transaction request for example TRXTYPE A amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp ORIGID EFHPOCDBF5C7 This is the Do Authorization response RESULT 0 amp PNREF EFHPOCDCG6C8 amp RESPMSG Approved amp PPREF 30600078M3553652G 2 To capture the Do Authorization set ORIGID PNREF PNREF returned in the Do Authorization response and TRXTYPE D for example TRXTYPE Dcg amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp OR IGID EFHPOCDBF6C8 Do Reauthorization To reauthorize an Authorization for an additional three day honor period you can use a Do Reauthorization transaction A Do Reauthorization can be used at most once during the 29 day authorization period To set up a Do Reauthorization you must pass the following parameters in the request string e Set ORIGID PNREF PNREF returned in the original Authorization response e Set TRXTYPE A e Set DoReauthorization 1 This is an example Do Reauthorization request with required parameters 36 Express Checkout for Payflow Express Checkout Transaction Types Do Authorization TRXTYPE A amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp ORIGID EFHPOCDBF5C7 amp DOREAUTHORIZATION 1 Do Authorization A Do Authorization transaction represents an ag
40. PayPal Express Checkout for Payflow Express Checkout for Payflow Document Number 200042 en_US 201306 2013 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 S r l et Cie S C A Soci t 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 reser
41. QBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 45 alphanumeric characters Bill to state address NOTE The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 45 alphanumeric characters U S zip code or other country specific postal code NOTE The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 10 alphanumeric characters Bill to country code NOTE The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations Four alphanumeric characters Express Checkout for Payflow 65 66 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 6 Get Express Checkout Details response parameters Parameter ADDRESSSTATUS RESULT RESPMSG Description Status of the bill to address on file with PayPal The values are e Y confirmed e N unconfirmed The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations One alpha character Response value for the request Response message in case if any error occurs Do Express Checkout Payment Request Parameter Descriptions TABLE A 7 Do Express Checkout Payment request parameters Parameter TRXTYPE TENDER
42. Redirecting the Buyer to PayPal e Get Express Checkout Details ACTION G e Redirecting the Buyer to Your Website e Do Express Checkout Payment ACTION D Set Express Checkout ACTION S The Set Express Checkout request passes the transaction details from your website to PayPal when a buyer chooses to pay with PayPal Set Express Checkout requires that you pass data for the following parameters e ACTION e AMT Express Checkout for Payflow Express Checkout Processing Flow i Express Checkout Sale Transaction Example e RETURNURL e CANCELURL This is an example Set Express Checkout request for a Sale transaction TRXTYPE S amp ACTION S 35 00 amp CANCELURL http www order_page com amp CUSTOM TRVV14459 amp EMAIL buyer name abc com amp PARTNER partner amp PWD password amp RETURNURL ht tp www confirmation_page com amp TENDER P amp USER user amp VENDOR vendor It 15 strongly recommended that RETURNURL be the URL of the final review page on your website where the buyer confirms the order and payment Likewise CANCELURL should be the URL of the original page on your website where the buyer initially chose to use PayPal This is a response to the request RESULT 0 amp RESPMSG Approved amp TOKEN EC 17C76533PL706494P RESULT and RESPONSE values are returned with all transactions In a successful response the value of RESULT is 0 For details on the set of response parameters generally pa
43. TE parameter 38 76 CITY parameter 65 COLOR parameter 60 CORRELATIONID parameter 42 COUNTRYCODE parameter 65 currency code format 57 58 68 69 81 82 currency codes 85 CURRENCY parameter 55 80 CUSTIP parameter 79 CUSTOM parameter 59 64 67 80 Customer Support 7 CVV2MATCH parameter 43 Czech Koruna 85 D Danish Krone 85 DISCOUNT parameter 63 82 Dollar 85 86 E EMAIL parameter 61 62 Euro 85 Express Checkout ACTION values 12 overview of process 9 Set Express Checkout example 12 Express Checkout flow 11 F FEEAMT parameter 71 FIRSTNAME parameter 63 78 Forint 85 Franc 85 FREIGHTAMT parameter 82 H HANDLINGAMT parameter 82 HDRBACKCOLOR parameter 60 HDRBORDERCOLOR parameter 60 HDRIMG parameter 60 Hong Kong Dollar 85 Hungarian Forint 85 INVNUM parameter 59 64 67 80 Israeli New Sheqel 85 ITEMAMT parameter 81 J Japanese Yen 85 K Koruna 85 Krona 85 Krone 85 L L_BILLINGAGREEMENTDESCRIPTIONn parameter 56 L_BILLINGTYPEn parameter 56 L_COSTn parameter 57 81 L_DESCn parameter 57 80 L_NAMEn parameter 57 80 L_QTYn parameter 57 81 L_TAXAMTn parameter 57 68 81 LASTNAME parameter 63 78 LOCALECODE parameter 60 Malaysian Ringgit 85 MAXAMT parameter 59 MEMO parameter 75 MerchantInitiatedBilling 20 Mexican Peso 85 N New Dollar 85 New Shegel 85 New Zealand Dollar 85 Norwegian Krone 85 NOSHIPPING parameter 59 NOTE parameter 63 71 75 NOTIFYURL parameter 67 80 94 O
44. V Country EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA 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 Express Checkout for Payflow Code GQ ER EE ET FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GG Country GUINEA GUINEA BISSAU GUYANA HAITI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE VATICAN CITY STATE HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN ISLAMIC REPUB LIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA DEMOCRATIC PEOPLE S REPUBLIC OF Express Checkout for Payflow Code GN GW GY HT HM VA HN HK HU IS IN ID IR IQ IE IM IL IT JM JP JE q Country KOREA REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE S DEMO CRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO Code KR KW KG LA LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX 89
45. XTYPE O Limitations 12 case sensitive alphanumeric characters NOTE Optional An informal note about this settlement that is displayed to the buyer in email and in the buyer s transaction history Limitations 255 character string TABLE A 14 Void response parameters Parameter Description PPREF Unique PayPal transaction ID Limitations 17 character string RESULT Response value for the request RESPMSG Response message in case if any error occurs Credit Parameter Descriptions TABLE A 15 Credit request parameters Parameter Description TRXTYPE Required Type of transaction to perform The value is C Limitations One alpha character TENDER Required The tender type method of payment It is always P Limitations One alpha character ORIGID Required Payflow transaction ID Set this parameter to the value of the PNREF returned in the original Authorization or Order Do Express Checkout Payment transaction response Limitations 12 case sensitive alphanumeric characters AMT Optional Required if the amount to credit differs from the original Sale or Delayed Capture amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 74 Express Checkout for Payflow Express Checkout Parameter Reference Delayed Capture Paramet
46. YPE BILLINGTYPE will be ignored Each L BILLINGTYPEn must have a corresponding description string 1 BILLINGAGREEMENTDESCRIPTIONn See PayPal Payments Pro Payflow Edition Recurring Payments Developer s Guide for details on creating Recurring Payments profiles Character length and limitations A string n is a value in the range 0 9 Optional Describes the billing type for a PayPal account that will be billed with Recurring Payments See L_BILLINGTYPEn Character length and limitations A string n is a value in the range 0 9 Optional Describes the billing type for a PayPal account The possible values are e MerchantInitiatedBilling Use this value to obtain a BAID in the Set Express Checkout flow e RecurringPayments Use this value to use the TOKEN returned in the Set Express Checkout response to create a Recurring Payments profile See PayPal Payments Pro Payflow Edition Recurring Payments Developer s Guide for details on creating Recurring Payments profiles Character length and limitations A string n is a value in the range 0 9 Optional Describes the billing agreement for a PayPal account If BILLINGTYPE is RecurringPayments BA_DESC is required Limitations 255 character string Optional Custom annotation field for your exclusive use with billing agreements Limitations 255 character string 56 Express Checkout for Payflow Express Checkout Parameter Reference Express Checkout Paramet
47. ain a BAID You can obtain a BAID whether or not the buyer logs in to PayPal to make a purchase The following sections describe how 20 Express Checkout for Payflow Billing Agreements and Reference Transactions Obtaining the BAID With Express Checkout Purchase e When the buyer is making a purchase Say that you have implemented Express Checkout on your website The buyer logs in to purchase an item of merchandise and chooses PayPal to pay for it In the normal Express Checkout flow the buyer is then redirected to PayPal to log in to verify their billing information If the buyer approves payment on the PayPal Review page you receive the billing agreement as part of the transaction You can use that billing agreement later to bill the buyer a set amount on a recurring basis such as once a month for future purchases The buyer doesn t need to log into PayPal each time to make a payment e When the buyer is not making a purchase Typically the buyer chooses a billing agreement without making a purchase when they subscribe for merchandise they will pay for on a recurring schedule If for example the buyer logs in to your website to order a magazine subscription you set up an agreement to bill the buyer a scheduled basis say once a month In the billing agreement flow without purchase the buyer is redirected to PayPal to log in On the PayPal site they consent to the billing agreement Next month when you send the buyer the firs
48. ale for which you are requesting payment NOTE You cannot set this value to S in the Set Express Checkout request and then change this value to A on the final Do Express Checkout Payment request Limitations One alpha character TENDER Required The tender type method of payment It is always P Limitations One alpha character ACTION Required Is G to indicate this is a Get Express Checkout Details request Limitations One alpha character TOKEN Required A time stamped token the value of which was returned in the Set Express Checkout response Limitations 20 character alphanumeric string Get Express Checkout Details Response Parameter Descriptions TABLE A 6 Get Express Checkout Details response parameters Parameter Description TOKEN The time stamped token value that was returned in the Set Express Checkout response Limitations 20 character alphanumeric string EMAIL Email address of the buyer as entered during checkout Limitations 127 character alphanumeric string PAYERID Unique PayPal buyer account identification number Limitations 13 character string 62 Express Checkout for Payflow Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 6 Get Express Checkout Details response parameters Parameter PAYERSTATUS DISCOUNT INSURANCEAMT NOTE ADJUSTMENTAMT FIRSTNAME LASTNAME Description Status of buyer Values are e verified e unveri
49. all items in this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Required if L TAXAMTn is specified Sum of tax for all items in this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Total shipping cost for this order NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 68 Express Checkout for Payflow Express Checkout Parameter Reference A Express Checkout Parameter Descriptions TABLE A 7 Do Express Checkout Payment request parameters Parameter Description HANDLINGAMT Optional Total handling cost for this order NorE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decima
50. apter 2 Billing Agreements and Reference Transactions 19 About Reference 19 About Billing Agreements 20 About Billing 20 Ways Obtain a BAID 20 Obtaining the BAID With Express Checkout Purchase 21 Example of Obtaining the BAID With Express Checkout 24 Obtaining the BAID Without Express Checkout 25 Example of Obtaining the BAID Without Express Checkout Purchase 28 Express Checkout for Payflow Contents Updating a Billing Agreement 29 Example of Updating a Billing 29 Using Reference 30 Reference Transaction Request Passing the 30 Reference Transaction Request Passing the PNREF Value ORIGID 31 Chapter 3 Express Checkout Transaction Types 33 Honor Period and Authorization Period 33 Payment Transaction 33 I u ee S Q S Bee eG 34 2 4 4 EA s ua ee Q la w JS Q wa 34 abd A ee Awe ee
51. billing agreement Limitations 19 character string Returns one of the following values e instantonly The payment is made with no delay e The payment may be made with no delay or the payment is pending see PENDINGSTATUS Limitations 11 characters 70 Express Checkout for Payflow Express Checkout Parameter Reference A Express Checkout Parameter Descriptions TABLE A 8 Do Express Checkout Payment response parameters Parameter Description TAXAMT Sum of tax for all items in this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 FEEAMT Processor charge for the transaction Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 NOTE Is 0 default or 1 If ALLOWNOTE is set to 1 in the Set Express Checkout request NOTE will contain the text entered by the buyer in the Express Checkout flow Limitations 255 character string PENDINGREASON The reason the payment is pending Values are e none No pending reason e address The payment is pending because your buyer did not include a confirmed shipping address and your Payment Receiving Preferences is set suc
52. cate suppression time out Express Checkout for Payflow 47 Transaction Responses RESULT Values and RESPMSG Text TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 108 Void error See RESPMSG Make sure the transaction ID entered has not already been voided If not then look at the Transaction Detail screen for this transaction to see if it has settled The Batch field is set to a number greater than zero if the transaction has been settled If the transaction has already settled your only recourse is a reversal credit a payment or submit a payment for a credit 109 Time out waiting for host response 110 Referenced auth against order Error 111 Capture error Either an attempt to capture a transaction that is not an authorization transaction type or an attempt to capture an authorization transaction that has already been captured 112 Failed AVS check Address and ZIP code do not match An authorization may still exist on the cardholder s account 113 Merchant sale total will exceed the sales cap with current transaction ACH transactions only 114 Card Security Code CSC Mismatch An authorization may still exist on the cardholder s account 115 System busy try again later 116 VPS Internal error Failed to lock terminal number 117 Failed merchant rule check One or more of the following three failures occurred An attempt was made to submit a transaction that failed to
53. ckout Parameter Reference A Express Checkout Parameter Descriptions Express Checkout Parameter Descriptions Set Express Checkout Request Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter Description TRXTYPE Required How you want to obtain payment e Aindicates that this payment is an Authorization subject to settlement with the Delayed Capture request Oindicates that this payment is an Order subject to settlement with the Delayed Capture request e S indicates that this is a final Sale for which you are requesting payment NOTE You cannot set this value to S in the Set Express Checkout request and then change this value to A on the final Do Express Checkout Payment request Limitations One alpha character TENDER Required The tender type method of payment It is always P Limitations One alpha character ACTION Required Is S to indicate this is a Set Express Checkout request Limitations One alpha character AMT Required Amount US Dollars U S based currency NOTE You must set CURRENCY to one of the currency codes for any of the supported PayPal currencies Set AMT 0 00 when passing the billing type value Merchant InitiatedBilling to use the TOKEN returned by the Set Express Checkout response as a parameter in a request to create a billing agreement Limitations Must not exceed 10 000 USD in any currency Nine numeric characers plus decimal character No curr
54. cter No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Express Checkout for Payflow 81 Express Checkout Parameter Reference Reference Transaction Parameter Descriptions TABLE A 23 Reference Transaction Request Parameters Parameter TAXAMT FREIGHTAMT HANDLINGAMT DISCOUNT 5 SHIPTOSTREET Description Required if L TAXAMTn is specified Sum of tax for all items in this order TAXAMT L QTYO L L 1 1 1 L L TAXAMIn NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal Optional Total shipping cost for this order NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199
55. de the values PROXYPORT Optional Proxy server port Express Checkout for Payflow 53 Express Checkout Parameter Reference User Parameter Descriptions TABLE A 1 Connection request parameters Parameter Description PROXYLOGON Optional Proxy server logon ID PROXYPASSWORD Optional Proxy server logon password User Parameter Descriptions All Payflow transaction requests require the user parameters described below TABLE A 2 User request parameters Parameter Description USER Required If you set up one or more additional users on the account this value is the ID of the user authorized to process transactions If however you have not set up additional users on the account USER has the same value as VENDOR Limitations 64 alphanumeric case sensitive characters Limitations 64 alphanumeric case sensitive characters VENDOR Required Your merchant login ID that you created when you registered for the account Limitations 64 alphanumeric case sensitive characters Limitations 64 alphanumeric case sensitive characters PARTNER Required The ID provided to you by the authorized PayPal Reseller who registered you for the Payflow service Limitations 12 alphanumeric case sensitive characters PWD Required The password that you defined while registering for the account Limitations Six to thirty two alphanumeric case sensitive characters 54 Express Checkout for Payflow Express Che
56. e D TRXTYPE Required Is A Authorization or S Sale BAID Required PayPal Paymentech Salem processors BAID returned from Create Customer Billing Agreement If you pass BATD do not pass ORIGID ORIGID Required other Payflow processors PNREF returned from Create Customer Billing If you pass ORIGID do not pass CUSTIP Optional IP address of payer s browser as recorded in its HTTP request to your website NOTE PayPal records this IP address as a means to detect possible fraud Limitations 15 character string in dotted quad format xxx xxx xxx xxx Express Checkout for Payflow 79 80 Express Checkout Parameter Reference Reference Transaction Parameter Descriptions TABLE A 23 Reference Transaction Request Parameters Parameter PAYMENTTYPE REQCONFIRMSHIPPING CURRENCY ORDERDESC CUSTOM INVNUM BUTTONSOURCE NOTIFYURL L NAMEN L DESCn Description Optional Is one of the following values e instantonly The payment is made with no delay e The payment may be made with no delay or the payment is pending Limitations 11 characters Optional Is 1 or 0 The value 1 indicates that you require that the buyer s shipping address on file with PayPal be a confirmed address Setting this element overrides the setting you have specified in your Merchant Account Profile Limitations One character Required One of the supported currency codes See Appendi
57. e Peso PLN Polish Zloty GBP Pound Sterling SGD Singapore Dollar SEK Swedish Krona CHF Swiss Franc TWD Taiwan New Dollar Express Checkout for Payflow 85 Currency Codes TABLE B 1 Currencies and Currency Codes Code Currency THB Thai Baht USD U S Dollar 86 Express Checkout for Payflow Country Codes This table lists country codes defined by ISO 3166 1 BELARUS BY Table 1 Country Codes BELGIUM BE Country Code BELIZE BZ AFGHANISTAN AF BENIN BJ ALAND ISLANDS AX BERMUDA BM ALBANIA AL BHUTAN BT ALGERIA DZ BOLIVIA BO AMERICAN SAMOA AS BOSNIA AND HERZE BA ANDORRA AD OVINA BOTSWANA BW ne BOUVET ISLAND BV ANTARCTICA AQ BRAZEN BR ETE BRUNEIDARUSSALAM BN us BULGARIA BG BURKINA FASO BF AUSTRALIA AU PURUNDI AUSTRIA AT CAMBUL CAMEROON CM BAHAMAS BS CANADA VERDE Puas w CAYMAN ISLANDS KY BARBADOS BB Express Checkout for Payflow Country Codes 88 Country CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS KEELING ISLANDS COLOMBIA COMOROS CONGO CONGO THE DEMO CRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR Code CF TD CL CN CC CO CG CD CK CR CI HR CU CY CZ DK DJ DM DO EC EG S
58. e response string The value of RESULT indicates the overall status of the transaction attempt e A value of zero indicates that no errors occurred and the transaction was approved e A value less than zero indicates that a communication error occurred In this case no transaction is attempted e A value greater than zero indicates a decline or error except the case of RESULT 104 See the table below The response message RESPMSG provides a brief description for decline or error results RESULT Values for Transaction Declines or Errors For non zero RESULT values the response string includes a RESPMSG name value pair The exact wording of the RESPMSG shown in bold may vary Sometimes a colon appears after the initial RESPMSG followed by more detailed information When interpreting RESULT values for the PayPal processor note the following e When RESULT 0 warning information may be returned that is useful to the request application See the PayPal API documentation on Developer Central for detailed information on corrective actions e When RESULT 104 you must log in to the PayPal website to determine if the transaction actually went through If the transaction does not appear in the History section you should retry it Source Responses TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 0 Approved 1 User authentication failed Error is caused by one or more of the foll
59. e the BAID to implement Payflow reference transactions Express Checkout for Payflow 27 Billing Agreements and Reference Transactions Obtaining the BAID Without Express Checkout Purchase Example of Obtaining the BAID Without Express Checkout Purchase This section provides an example of obtaining the BAID The billing agreement parameters and AMT which must be 0 are shown in boldface Set Express Checkout Request ACTION S The following is an example of a Set Express Checkout request that passes billing agreement parameters IMPORTANT Even though no payment is sent the value of TRXTYPE must be A in the request strings PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION S amp TENDER P amp RETURNURL http return com amp CANCELURL http cancel com 0 00 DESC purchase Time magazine amp BILLINGTYPE MerchantInitiatedBilling amp PAYMENTTYPE any CUSTOM magazine subscription Set Express Checkout Response RESULT 0 amp RESPMSG Approved amp TOKEN EC 36X58962RS656712N amp CORRELATIONID a3 98b1f 35ebfa Create Customer Billing Agreement Request ACTION X The Create Customer Billing Agreement request passes the TOKEN returned in the Set Express Checkout response PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION X amp TENDER P amp TOKEN EC 36X58962RS656712N Create Custom
60. ect your buyer to the PayPal website The redirect URL for this is shown below TOKEN is the value returned in the Set Express Checkout response https www paypal com cgi bin webscr cmd _express checkout amp token lt TOKEN gt The buyer is presented with a PayPal Review page such as the example page shown in Figure 2 4 The buyer must click Agree and Continue for steps 5 through 8 below to occur FIGURE 2 4 PayPal Review page jimmie logan s Test Store Review your information PayPal Secure Payments After clicking Agree and Continue you will be re directed to jimmie logan s Test Store View PayPal policies and your payment source rights Payment Method Available Funding Sources Contact Information jsmith paypal corn 408 678 0945 Change authorize jimmie logan s Test Store to charge the available funding sources in my PayPal account based on PayPal s default preferences for future payments PayPal will not share my financial information with this merchant How does itwork Agree and Continue Cancel and return to jimmie logan s Test Store 4 PayPal redirects the buyer s browser to your return page 5 Call the Get Express Checkout Details request ACTION G to obtain information about the buyer PayPal returns the buyer information including whether the billing agreement was accepted 6 Call the Create buyer Billing Agreement request ACTION X to obtain the BAID 7 PayPal returns a BAID Sav
61. ed to research a specific transaction with PayPal Limitations 17 character string The response message returned with the transaction result Exact wording varies Sometimes a colon appears after the initial RESPMSG followed by more detailed information NOTE The PayPal processor may also return a warning message in the RESPMSG string when RESULT 0 For more information on corrective actions see the PayPal developer documentation on Developer Central Limitations Alphanumeric Value used for tracking Limitations 13 character alphanumeric string Address Verification Service Responses From PayPal The table below compares the detailed response returned by the PayPal processor for address verification to the normalized response value Y N or X returned in the AVSADDR and AVSZIP response parameters If you want to obtain the PayPal processor value set the VERBOSITY parameter to MEDIUM With this setting the processor value is returned in the PROCAVS response parameter TABLE 4 2 Address Verification Service response value mapping PayPal Processor Address Verification Service Code Meaning A Address B International A C International N D International X E F UK specific X G Global Unavailable Not allowed for MOTO Internet Phone transactions International Unavailable AVSADDR AVSZIP x x lt x lt Z lt lt x x lt x lt Z Z Z Express Checkout for Payflow
62. ence transaction takes existing billing information already gathered from a previously authorized transaction and reuses it to charge the buyer in a subsequent transaction Before you can use a reference transaction you must set up a billing agreement with the buyer See About Billing Agreements When you obtain the billing agreement you can withdraw funds from the buyer s PayPal account without manual intervention using a reference transaction You can only use reference transactions with Authorization or Sale transactions TRXTYPE is Aor S To enable line item support in reference transactions which includes the parameters below you must contact Merchant Technical Support at http www paypal com mts e L NAMEN e L DESCn e L COSTn e L TAXAMTn L QTYn Express Checkout for Payflow 19 Billing Agreements and Reference Transactions About Billing Agreements About Billing Agreements A billing agreement allows PayPal to withdraw funds from the buyer s PayPal account without requiring the buyer to log in to PayPal Billing agreements are maintained by PayPal You must establish a billing agreement with a buyer if for example you and the buyer agree that you will bill that buyer on a regularly scheduled basis such as monthly for a magazine subscription Before a billing agreement can take effect the buyer must log in to PayPal once to consent to it With buyer consent PayPal creates a billing agreement ID BAID to
63. ency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal CURRENCY Required One of the supported currency codes See Currency Codes on page 85 RETURNURL Required URL to which the buyer s browser is returned after choosing to pay Limitations Character string with no maximum length Express Checkout for Payflow 55 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter CANCELURL TOKEN L_BILLINGTYPEn L_BILLINGAGREEMEN TDESCRIPTIONn BILLINGTYPE DESC CUSTOM Description Required URL to which the buyer is returned if the buyer cancels the order Limitations Character string with no maximum length Optional Include this parameter to modify an existing Sale or Authorization request The value is returned in a previous Set Express Checkout response Limitations 20 character alphanumeric string Optional Describes the billing type for a PayPal account that will be billed with Recurring Payments Set to RecurringPayments to use the TOKEN returned in the Set Express Checkout response to create a Recurring Payments profile Either L BILLINGTYPEn or BILLINGTYPE must be passed to create a Recurring Payments profile If you pass L BILLINGTYPEn and BILLINGT
64. er Billing Agreement Response The response returns the BATD 28 Express Checkout for Payflow Billing Agreements and Reference Transactions Updating a Billing Agreement RESULT 0 amp PNREF E24P0A03B013 amp RESPMSG Approved amp TOKEN EC 36X58962RS656712N amp PPREF 44000000000180903 amp CORRELATIONID 3a3204997455r amp BAID B 12345678901234567 Updating a Billing Agreement You can use the Update Billing Agreement request to cancel the billing agreement or update the billing agreement description Some points to note Do not pass TRXTYPE with this transaction e BAIDis the only required parameter ACTION U e The only value you can pass for STATUS is cancel to change the billing agreement status e You can change the billing agreement description by entering a different string value for BA DESC e The response does not return a PNREF PayPal responds with the BAID and other information about the buyer whose agreement was updated Although a buyer can log in to PayPal to manage agreements the Update Billing Agreement request enables the buyer to cancel an agreement from your website without logging in to PayPal You can provide your own page for maintaining agreements with the buyer Example of Updating a Billing Agreement The following is an example of updating a billing agreement description Billing agreement parameters are shown in boldface Request PARTNER partner amp VENDOR vendor amp PW
65. er Descriptions TABLE A 15 Credit request parameters Parameter Description MEMO Optional Custom memo about the credit Limitations 255 alphanumeric characers TABLE A 16 Credit response parameters Parameter Description PPREF Unique PayPal transaction ID Limitations 17 character string RESULT Response value for the request RESPMSG Response message in case if any error occurs Delayed Capture Parameter Descriptions TABLE A 17 Delayed Capture request parameters Parameter Description TRXTYPE Required Type of transaction to perform The value is D Limitations One alpha character TENDER Required The tender type method of payment It is always P Limitations One alpha character ORIGID Required Payflow transaction ID Set this parameter to the value of the PNREF returned in the original Authorization or Order Do Express Checkout Payment transaction response Limitations 12 case sensitive alphanumeric characters AMT Optional Required if the capture amount differs from the original Authorization amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 NOTE Optional An informal note about this settlement that is displayed to the buyer in email and in the buyer s transaction history Limitations 255 character
66. er Descriptions TABLE A 3 Set Express Checkout request parameters Parameter PAYMENTTYPE L NAMEN L DESCn L_COSTn L_TAXAMTn L_QTYn ITEMAMT Description Optional Is one of the following values e instantonly The payment is made with no delay e any The payment may be made with no delay or the payment is pending Limitations 11 characters Optional Line item name Character length and limitations 36 alphanumeric characters Optional Line item description for each different item purchased such as hiking boots or cooking utensils NOTE You can view line item information in the Transaction Details report in your PayPal merchant account Limitations 35 character string Required if L is supplied Cost of the line item The line item unit price can be a positive or a negative value but not 0 NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal Optional Line item tax amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use
67. ers 76 Create Customer Billing Agreement Response Parameters 77 Update Customer Billing Agreement Request Parameters 77 Update Customer Billing Agreement Response Parameters 78 Reference Transaction Parameter 79 Reference Transaction Request Parameters 79 Reference Transaction Response Parameters 83 Appendix B Currency 285 Appendix C Country Codes 87 93 Express Checkout for Payflow 5 Contents 6 Express Checkout for Payflow Preface Intended Audience This guide assumes that its readers e Are experienced web or application developers e Have a background in payments services e Are developing payment services applications that are integrating Express Checkout to process transactions to be sent over the Payflow gateway Related Documentation For additional information on Payflow documentation go to the Inteeraion Guides page and for the Payflow SDKs go to http paypal github io How to Contact Customer Support For problems with transaction processing or your connection to the server contact Customer Support by opening a ticket on the under Contact Support tab at http www paypal com mts Document History TABLE 3 1 Document history Date D
68. escription June 2013 Updated the description of the REQBILLINGADDRESS field in the Set Express Checkout request parameters table Updated URLs Updated the account creation instructions in the Testing Your Integration Using the Sandbox section April 2012 Updated references to Website Payments Pro to PayPal Payments Pro October 2009 Updated currency codes Express Checkout for Payflow Document History TABLE 3 1 Document history Date Description August 2009 Revised and updated Added reference transactions and RecurringPayments billing type Revised billing agreements Removed PayPal Button Placement Added Eliminating Your Order Review Page to Chapter 1 Express Checkout Processing Flow June 2009 Added 5 parameter May 2009 Updated to correct for technical inaccuracies April 2009 Added creating billing agreements for setting up Recurring Payments through Express Checkout Added order line item details parameters Updated with PHONENUM parameter in Set Express Checkout request 8 Express Checkout for Payflow Express Checkout Processing Flow This chapter describes Express Checkout processing What Is Express Checkout on page 9 How Express Checkout Works on page 9 Express Checkout Flow on page 11 Express Checkout Sale Transaction Example on page 12 Other Express Checkout Concepts on page 16 What 15 Express Checkout Exp
69. esponses RESULT Values and RESPMSG Text TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 26 Invalid vendor account Login information is incorrect Verify that USER VENDOR PARTNER and PASSWORD have been entered correctly VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow user All fields are case sensitive 27 Insufficient partner permissions 28 Insufficient user permissions 29 Invalid XML document This could be caused by an unrecognized XML tag or a bad XML format that cannot be parsed by the system 30 Duplicate transaction 31 Error in adding the recurring profile 32 Error in modifying the recurring profile 33 Error in canceling the recurring profile 34 Error in forcing the recurring profile 35 Error in reactivating the recurring profile 36 OLTP Transaction failed 37 Invalid recurring profile ID 50 Insufficient funds available in account 51 Exceeds per transaction limit 99 General error See RESPMSG 100 Transaction type not supported by host 101 Time out value too small 102 Processor not available 103 Error reading response from host 104 Timeout waiting for processor response Try your transaction again 105 Credit error Make sure you have not already credited this transaction or that this transaction ID is for a creditable transaction For example you cannot credit an authorization 106 Host not available 107 Dupli
70. fied Limitations 10 character string Shipping discount for this order Specify the discount as a positive amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Total shipping insurance cost for this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Is 0 default or 1 If ALLOWNOTE is set to 1 in the Set Express Checkout request NOTE will contain the text entered by the buyer in the Express Checkout flow Limitations 255 character string A discount or gift certificate offered by PayPal to the buyer This amount will be represented by a negative amount If the buyer has a negative PayPal account balance PayPal adds the negative balance to the transaction amount which is represented as a positive value The negative amount is returned for Payflow merchants To test this value as a negative amount agaist the simulator send the amount as 1250 in the Set Express Checkout request and use the returned TOKEN in the Get Express Checkout Details request to see the ADJUSTMENTAMT response as a negative value Limitations Nine numeric characers plus decimal character No
71. for each different item purchased such as hiking boots or cooking utensils NOTE You can view line item information in the Transaction Details report in your PayPal merchant account Limitations 35 character string Express Checkout for Payflow 67 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 7 Do Express Checkout Payment request parameters Parameter L COSTn L_TAXAMTn L_QTYn ITEMAMT TAXAMT FREIGHTAMT Description Required if L is supplied Cost of the line item The line item unit price can be a positive or a negative value but not 0 NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal Optional Line item tax amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Required if L_COSTn is supplied Line item unit quantity Limitations 10 character integer Required if L COSTn is specified Sum of cost of
72. g parameters in the request string e Set ORIGID PNREF PNREF value returned in the response to the original Sale or Delayed Capture e Set TRXTYPE C e Set the value for AMT if the amount of the credit differs from the original Sale or Delayed Capture transaction This is an example Credit request with the required parameters set Express Checkout for Payflow 39 Express Checkout Transaction Types Credit TRXTYPE C amp TENDER P PARTNER partner VENDOR vendor amp USER user amp PWD password amp ORIGID EFHP0D426A62 45 00 Say for example a buyer purchases merchandise from a particular merchant using the buyer s PayPal account The merchant can send a Memo Post Sale above transaction to Paymentech so Paymentech can include that Sale information in the merchant s Paymentech account The advantage to the merchant is that the merchant can view PayPal Sale activities in their Paymentech reports The merchant uses a Memo Post Credit to send the buyer s Credit transaction information to Paymentech so the merchant can see the buyer s Credit information in their Paymentech reports 40 Express Checkout for Payflow Transaction Responses Transaction response parameters indicate the status of the transaction and return requested information e Response Parameters e Address Verification Service Responses From PayPal e Card Security Code Results e PNREF Value e RESULT Values and RESPMSG Text
73. h 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 echeck The payment is pending because it was made by an eCheck that has not yet cleared e intl payment is pending because you hold 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 You 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 completed The payment has been completed and the funds have been added successfully to your account balance e other The payment is pending for a reason other than those listed above For more information contact PayPal Customer Service RESULT Response value for the request RESPMSG Response message in case if any error occurs Express Checkout for Payflow 71 Express Checkout Parameter Reference Do Authorization Parameter Descriptions Do Authorization Parameter Descriptions TABLE A 9 Do Authorization request parameters Parameter TRXTYPE TENDER ORIGID Description Required The type of transaction to perform For a Do Authorization
74. he buyer has paid with an eCheck In such a case funds are not guaranteed and you should not ship or deliver items or services until the payment has successfully completed Norte PayPal recommends that you block eChecks as a payment method in your PayPal account profile if you are unable to handle pending state payments To find out the status of a pending payment you can e Submit an Inquiry transaction e Check the status from the PayPal User Interface See PayPal online help for details Express Checkout for Payflow 17 il Express Checkout Processing Flow Other Express Checkout Concepts 18 Express Checkout for Payflow Billing Agreements and Reference Transactions This chapter describes how you can automatically bill a buyer s PayPal account based on buyer information you obtained in a previous transaction To perform this type of transaction you first must obtain a billing agreement between you and the buyer e About Reference Transactions on page 19 e About Billing Agreements on page 20 e Ways To Obtain a BAID on page 20 e Obtaining the BAID With Express Checkout Purchase on page 21 e Obtaining the BAID Without Express Checkout Purchase on page 25 e Updating a Billing Agreement on page 29 e Using Reference Transactions on page 30 IMPORTANT You must be enabled by PayPal to use reference transactions Contact PayPal for details About Reference Transactions refer
75. imitations 20 character alphanumeric string Required Must be A Express Checkout for Payflow Express Checkout Parameter Reference Billing Agreement Parameter Descriptions TABLE A 19 Create Customer Billing Agreement request parameters Parameter Description TENDER Required The tender type method of payment It is always P Limitations One alpha character Create Customer Billing Agreement Response Parameters TABLE A 20 Create Customer Billing Agreement response parameters Parameter Description BAID The billing agreement ID Limitations 19 character string time stamped token the value of which was returned the Set Customer Billing Agreement response Limitations 20 character alphanumeric string RESULT Response value for the request RESPMSG Response message in case if any error occurs Update Customer Billing Agreement Request Parameters TABLE A 21 Update Customer Billing Agreement request parameters Parameter Description ACTION Required Is U to indicate this is an Update Billing Agreement request Limitations One alpha character TENDER Required The tender type method of payment It is always P Limitations One alpha character BAID Required The billing agreement ID Limitations 19 character string BA CUSTOM Optional Custom annotation field for your exclusive use Limitations 255 character string BA DESC Optional Description of goods or
76. l point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 DISCOUNT Optional Shipping discount for this order Specify the discount as a positive amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 INSURANCEAMT Optional Total shipping insurance cost for this order Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 SHIPTONAME Optional Ship to name Limitations 32 character string SHIPTOSTREET Optional Ship to street address If you include a shipping address and provide a value for the ADDROVERRIDE parameter PayPal returns this same address in the Get Express Checkout Details response Limitations 30 character string SHIPTOSTREET2 Optional Extended Ship to street address Example Bldg 6 Mail Stop 3 Limitations 30 character string SHIPTOCITY Optional Ship to city If SHIPTOCITY is passed you also must pass SHIPTOSTREET SHIPTOSTATE SHIPTOZIP and SHIPTOCOUNTRY Limitations 40 character string SHIPTOSTATE Optional Ship to state If SHIPTOSTATE is passed you also must pass SHIPTOSTREET SHIPTOCITY SHIPTOZIP and S
77. l test transaction requests as POSTs to the Payflow host address https pilot payflowpro paypal com e Send Express Checkout redirects to https www sandbox paypal com cgi bin webscr cmd _express checkout amp token lt ec token gt Express Checkout for Payflow 51 Express Checkout Testing Testing Your Integration Using the PayPal Simulator NorE You must be logged into the Sandbox before redirecting You should also create a Buyer account in the Sandbox to make test Express Checkout purchases against your Seller account Be sure to add a positive balance to the Buyer account at the time of creation Testing Your Integration Using the PayPal Simulator To test your integration using the simulator direct all test transactions to the Payflow host address for testing https pilot payflowpro paypal com Transactions are processed through PayPal s simulated payment network enabling you to test the configuration and operation of your application or storefront with no money changing hands Norte You must activate your account and configure your application for live transactions in PayPal Manager before accepting real orders 52 Express Checkout for Payflow Express Checkout Parameter Reference This reference describes all parameters that can be used with the Express Checkout payment solution e Connection Parameter Descriptions on page 53 e User Parameter Descriptions on page 54 e Express Check
78. lement overrides the setting you have specified in your Merchant Account Profile Limitations One character Optional Is 1 or 0 The value 1 indicates that on the PayPal pages no shipping address fields should be displayed whatsoever Limitations Four character string Optional Is 1 or 0 The value 1 indicates that the PayPal pages should display the shipping address set by you in the shipping address SHIPTO parameters passed to this Set Express Checkout request not the shipping address on file with PayPal for this buyer Limitations Four character string Express Checkout for Payflow 59 60 Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 3 Set Express Checkout request parameters Parameter LOCALECODE PAGESTYLE HDRIMG HDRBORDERCOLOR HDRBACKCOLOR PAYFLOWCOLOR Description Optional Locale of pages displayed by PayPal during Express Checkout Limitations Two character string AT AU BE CA CH CN DE ES FR GB IT JP NL PL US Optional Sets the Custom Payment Page Style for payment pages associated with this button link PageStyle corresponds to the HTML variable page_style for customizing payment pages The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account Limitations 30 character alpha string Optional URL for
79. lue but not 0 You may provide a negative value to reflect a discount on an order for example Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 L_TAXAMTn Optional Line item tax amount Limitations Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 No currency symbol Limitations Six character currency L QTYn Optional Line item unit quantity Limitations 10 character integer AMT Required Amount US Dollars U S based currency TAXAMT FREIGHTAMT HANDLINGAMT INSURANCEAMT DISCOUNT NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Must not exceed 10 000 USD in any currency Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal ITEMAMT Required if L COSTn is specified Sum of cost of all items in this order ITEMAMT L QTYO LCOSTO L QTY1 LCOST1 L QTYn L COSTA Limitations Nine numeric characers plus decimal chara
80. n your own and therefore eliminate the need for an Order Review page on your site Of course when the buyer returns from PayPal you still call the Do Express Checkout Payment request to complete the transaction In this situation you would want the button text on the PayPal Review page to appear as Pay Now rather than Continue You control the button text through the value of the useraction variable You set this variable on the PayPal URL to which you redirect the buyer after calling Set Express Checkout As a best practice you should incorporate the Pay Now button text in the Express Checkout flow that redirects the buyer to PayPal from your shopping cart at the start of checkout Values and resulting button text are described below e If you do not set useraction or you set useraction to continue PayPal displays the button text Continue e Ifyou set useraction to commit PayPal displays the button text Pay Now To display the Pay Now button text for example append amp useraction commit to the redirect URL string as shown below where tokenvalue is the token value returned in the Set Express Checkout response https www paypal com cgi bin webscr cmd _express checkout amp token tokenvalue amp useraction commit Pending Responses If the Do Express Checkout Payment PENDINGREASON response is a value other than none or completed the payment is pending Typically this means t
81. ng the BAID With Express Checkout Purchase This section provides an example of Express Checkout Authorization request and response name value pair strings illustrating the billing agreement parameters Billing agreement parameters are shown in boldface Set Express Checkout Request ACTION S The following is an example of a Set Express Checkout request PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION S amp TENDER P amp RETURNURL http return com amp CANCELURL http cancel com amp AMT 10 00 DESC purchase Time Magazine amp BILLINGTYPE MerchantInitiatedBilling CUSTOM add magazine subscription amp PAYMENTTYPE any Set Express Checkout Response RESULT 0 amp RESPMSG Approved amp CORRELATIONID ec093d08c9 39 amp TOKEN EC 36X58 962RS656712N Get Express Checkout Details Request ACTION G The following request contains no new parameters PARTNER partner amp VENDOR vendor amp PWD password amp USER user amp TRXTYPE A amp ACTION G amp TENDER P amp TOKEN EC 36X58962RS656712N 24 Express Checkout for Payflow Billing Agreements and Reference Transactions Obtaining the BAID Without Express Checkout Purchase Get Express Checkout Details Response RESULT 0 amp RESPMSG Approved amp TOKEN EC F3BQJQG7UGVDL754 amp CORRELATIONID 9c3706997455e amp EMAIL j smith paypal com amp PAYERSTATUS verified amp FIRSTNAME Joe amp LASTNA
82. o the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 ORDERURL Optional Your URL for displaying information about this transaction such as receipt shipment tracking or order details Limitations 127 character alphanumeric string ORDERDESC Optional Description of items the buyer is purchasing Limitations 127 character alphanumeric string CUSTOM Optional Free form field for your own use Limitations 256 character alphanumeric string INVNUM Optional Merchant invoice number The merchant invoice number is used for authorizations and settlements and depending on your merchant bank will appear on your buyer s credit card statement and your bank reconciliation report If you do not provide an invoice number the transaction ID PNREF will be submitted Limitations Nine alphanumeric characters BUTTONSOURCE Optional Identification code for use by third party applications to identify transactions Limitations 32 alphanumeric characters NOTIFYURL Optional Your URL for receiving Instant Payment Notification IPN about this transaction If you do not specify NotifyURL the request the notification URL from your Merchant Profile is used if one exists Limitations 2048 alphanumeric characters L_NAMEn Optional Line item name Character length and limitations 36 alphanumeric characters L_DESCn Optional Line item description
83. oe Creek Regional Interiors amp SHIPTONAME J Smith amp SHIPTOSTREET 5262 Green Street 8 amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOZIP 95148 amp SHIPTOCOUNTRY US Redirecting the Buyer to Your Website PayPal redirects the buyer back to your website at the location you specified in the RETURNURL parameter to Get Express Checkout request To the URL string PayPal appends the TOKEN and PAYERID name value pairs as shown below http RETURNURL token lt TOKEN gt amp PayerID lt PAYERID gt You need to pass the PAYERID in the Do Express Checkout Payment request Do Express Checkout Payment ACTION D The Do Express Checkout Payment request performs the actual money transfer of the Sale transaction Do Express Checkout Payment request requires that you pass data for these parameters e ACTION e TOKEN e PAYERID e AMT The following is an example Do Express Checkout Payment request Express Checkout for Payflow 15 Express Checkout Processing Flow Other Express Checkout Concepts TRXTYPE S amp VENDOR vendor amp USER user amp PWD pwd amp TENDER P PARTNER partner amp ACTION D amp TOKEN EC 17C76533PL706494P amp PAYERID FHY4J0XY7CV9PG amp 35 00 The following is example response RESULT 0 amp PNREF EFHPOCDBF5C7 amp RESPMSG Approved amp AVSADDR Y amp TOKEN EC 17C76533PL706494P amp PAYERID FHY40XY7CV9PG amp PPREF 2P599077L3553652G amp PAYMENTTYPE instant
84. only The response returns a 12 character PNREF Payflow Transaction ID that is used to identify this transaction in PayPal reports Other Express Checkout Concepts The following topics are related to processing Express Checkout transactions e Obtaining the Buyer s Telephone Number During Checkout on page 16 e Pending Responses on page 17 e Eliminating Your Order Review Page on page 17 Obtaining the Buyer s Telephone Number During Checkout You have three options regarding the buyer s contact telephone number You can choose to e Not request the contact telephone number default e Request the contact telephone number as an optional field e Require that the buyer enter their contact telephone number to proceed If you choose to require the buyer provide a telephone number a telephone number displays in the Contact Information on the PayPal Review page during checkout Help text tells the buyer how to change the number displayed to their own number To choose one of the three preceding options 1 Log in to your PayPal account Express Checkout for Payflow Express Checkout Processing Flow Other Express Checkout Concepts 2 From the Profile tab click Website Payments Preferences 3 Choose from the three options for handling the contact telephone number at the bottom of the page Eliminating Your Order Review Page You can make checkout appear to complete on the PayPal website rather than o
85. or a Do Authorization subject to settlement with the Delayed Capture request Limitations One alpha character Required The tender type method of payment It is always P Limitations One alpha character Required Payflow transaction ID which is the value returned in the PNREF in the response to the original transaction when TRXTYPE A or TRXTYPE O Limitations 12 case sensitive alphanumeric characters Required Indicates whether this transaction is a Do Reauthorization The value is 1 TABLE A 12 Do Reauthorization response parameters Parameter PPREF RESULT RESPMSG Description Unique PayPal transaction ID Limitations 17 character string Response value for the request Response message in case if any error occurs Void Parameter Descriptions TABLE A 13 Void request parameters Parameter TRXTYPE TENDER Description Required Type of transaction to perform The value is V Limitations One alpha character Required The tender type method of payment It is always P Limitations One alpha character Express Checkout for Payflow 73 Express Checkout Parameter Reference Credit Parameter Descriptions TABLE A 13 Void request parameters Parameter Description ORIGID Required Payflow transaction ID Set this parameter to the value of the PNREF returned in the original transaction response when Do Express Checkout Payment request was submitted with TR
86. out Parameter Descriptions on page 55 e Do Reauthorization Parameter Descriptions on page 73 e Do Authorization Parameter Descriptions on page 72 e Void Parameter Descriptions on page 73 e Credit Parameter Descriptions on page 74 e Delayed Capture Parameter Descriptions on page 75 e Billing Agreement Parameter Descriptions on page 76 e Reference Transaction Parameter Descriptions on page 79 Connection Parameter Descriptions Pass the connection parameters in the format and syntax required by the Payflow gateway and programming language that you are using See your integration documentation for details TABLE A 1 Connection request parameters Parameter Description HOSTADDRESS Required Payflow host name HOSTPORT Required Use port 443 PARMLIST Required List of parameters that specify the payment information for the 5 transaction The quotation marks at the beginning and end are required The following is an example TRXTYPE S amp TENDER C amp PARTNER Partner amp VENDOR vendor amp USER user amp PWD password amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 The content of the PARMLIST varies by the type of transaction being processed For example a Void transaction requires a different set of parameters than a Sale PROXYADDRESS Optional Proxy server address Use the PROXY parameters for servers behind a firewall Your network administrator can provi
87. owing e Login information is incorrect Verify that USER VENDOR PARTNER and PASSWORD have been entered correctly VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow user All fields are case sensitive e Invalid Processor information entered Contact merchant bank to verify e Allowed IP Address security feature implemented The transaction is coming from an unknown IP address See PayPal Manager online help for details on how to use Manager to update the allowed IP addresses e You are using a test not active account to submit a transaction to the live PayPal servers Change the host address from the test server URL to the live server URL Express Checkout for Payflow 45 Transaction Responses RESULT Values and RESPMSG Text TABLE 4 5 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 2 Invalid tender type Your merchant bank account does not support the following credit card type that was submitted 3 Invalid transaction type Transaction type is not appropriate for this transaction For example you cannot credit an authorization only transaction 4 Invalid amount format Use the format Do not include currency symbols or commas 5 Invalid merchant information Processor does not recognize your merchant account information Contact your bank account acquirer to resolve this problem 6 Invalid or unsupported currency code 7
88. rameters in the Set Express Checkout Get Express Checkout Details and Do Express Checkout Payment requests e Set Express Checkout request TRXTYPE S ACTION S e Get Express Checkout Details request optional TRXTYPE S ACTION G e Do Express Checkout Payment request TRXTYPE S ACTION D After you send the Do Express Checkout Payment request for a Sale transaction which returns a RESULT value of 0 success the payment is complete and no further action is necessary You cannot capture a further payment or void any part of the payment For a detailed example of a Sale transaction see Express Checkout Sale Transaction Example Authorization An Authorization transaction represents an agreement to pay It places the buyer s funds on hold for a three day honor period is valid for 29 days It does not transfer funds If your business does not provide immediate fulfillment of products or services an Authorization enables you to capture funds with a Delayed Capture transaction when back ordered merchandise for example does become available You can capture up to the authorized amount specified in the original Authorization transaction If you are still not able to complete the Authorization and Delayed Capture within the 29 day period you can perform a one time extension of the Authorization using a Do Reauthorization Merchants get around these limitations by choosing to perform an Order Express Checkout for Payflow Express Checkout Transac
89. reement to pay and places the buyer s funds from the original Order transaction on hold for up to three days It does not transfer funds Note You can only use Do Authorization if the original transaction in the Express Checkout flow is an Order You cannot use Do Reauthorization against a Do Authorization To set up a Do Authorization you must pass the following parameters in the request string e Set ORIGID PNREF PNREF value returned in the original Order transaction response only Note Do not pass the PPREF returned from the original Order transaction in place of the PNREF e Set TRXTYPE A In this example the PNREF returned in the original Order response is EFHPOCDBF 7D9 This is the Do Authorization request string TRXTYPE A amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp ORIGID EFHPOCDBF7D9 Delayed Capture A Delayed Capture transaction captures authorized funds and transfers them to PayPal Once a capture is approved you will see the funds in your PayPal account You can capture up to the amount specified in the original Authorization Express Checkout for Payflow 37 38 Express Checkout Transaction Types Delayed Capture Complete Capture To set up a capture of the total amount in the original Authorization you must pass the following parameters in the Delayed Capture request string e Set ORIGID PNREF PNREF value returned in the original Authorization Do A
90. represent the agreement You pass the BAID in subsequent requests to bill the buyer PayPal withdraws funds without requiring the buyer to log in A billing agreement is good until you or the buyer cancels it A buyer may have multiple magazine subscriptions each with a separate billing agreement In such cases be sure to associate each transaction with the correct billing agreement About Billing Types To specify how the buyer will be billed you set the billing type in the call to Set Express Checkout Table 2 1describes the values of this parameter TABLE 2 1 Billing type values Value Description MerchantInitiatedBilling Use to obtain a BAID in the Express Checkout flow To initiate billing the buyer one or more times call Do Express Checkout Payment outside the Express Checkout flow and pass the BAID to bill the buyer RecurringBilling Use to obtain a BAID for creating a recurring billing profile to bill the buyer on a recurring basis See the Payflow Pro Recurring Billing Service User s Guide for details on using the BAID to create a recurring billing profile RecurringPayments Use to obtain a TOKEN for creating a recurring payments profile to bill the buyer on a recurring basis NorE This billing type does not create a BAID See PayPal Payments Pro Payflow Edition Recurring Payments Developer s Guide for details on using this billing type value to create a Recurring Payments profile Ways To Obt
91. ress Checkout is PayPal s method of payment It offers your buyers an easy convenient checkout experience by letting them use shipping and billing information stored securely at PayPal to check out so they don t have to re enter it on your website Like other Payflow transactions Express Checkout transaction requests send data as name value pair parameters and include this basic set of required parameters Connection parameters User parameters Transaction type TRXTYPE such as Sale TRXTYPE S Authorization TRXTYPE A or Order TRXTYPE 0 Tender type which is always PayPal TENDER P How Express Checkout Works The figure below summarizes the Express Checkout flow Express Checkout for Payflow Express Checkout Processing Flow How Express Checkout Works FIGURE 1 1 Express Checkout flow Merchant website i Request ws ex Pay Set Express Checkout API ACTION S Server 2 Response Token 3 PayPal Login L Redirect gt etps www paypal com cgi bin webser cmd _enpress checkout token EC 308S22678F3934250X 6 Example token value 4 HTTP Redirect RetumURL Token G ma Continue Confirm funding 5 source and address Request Token gt Get Express Checkout Details ACTION G 4 Response Shipping Address Telephone Number 6 Request Final Transaction Details API Thank Do Express Checkout Payment Server You ACTION D 7
92. s name Limitations 127 character string Free form field for your own use as set by you in the Set Express Checkout request Limitations 256 character alphanumeric string Merchant invoice number If you do not provide an invoice number the transaction ID PNREF will be submitted Limitations Nine character alphanumeric string Account holder s telephone number Limitations 20 character string The field mask is US numbers international numbers Express Checkout for Payflow Express Checkout Parameter Reference Express Checkout Parameter Descriptions TABLE A 6 Get Express Checkout Details response parameters Parameter BILLTONAME STREET STREET2 CITY STATE ZIP COUNTRYCODE Description Bill to name NOTE The bill to address details are returned returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 32 alphanumeric characters Bill to street NOTE The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 100 alphanumeric characters Second bill to street address NOTE The bill to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout Limitations 100 alphanumeric characters Bill to city address The bill to address details are returned only if RE
93. s received 1017 Buyer Authentication Service 3 D Secure error response is invalid An error response is received and the response is not well formed for a Validate Authentication transaction 1021 Buyer Authentication Service Invalid card type 1022 Buyer Authentication Service Invalid or missing currency code 1023 Buyer Authentication Service merchant status for 3D secure is invalid 1041 Buyer Authentication Service Validate Authentication failed missing or invalid PARES 1042 Buyer Authentication Service Validate Authentication failed PARES format is invalid 1043 Buyer Authentication Service Validate Authentication failed Cannot find successful Verify Enrollment 1044 Buyer Authentication Service Validate Authentication failed Signature validation failed for PARES 1045 Buyer Authentication Service Validate Authentication failed Mismatched or invalid amount in PARES 1046 Buyer Authentication Service Validate Authentication failed Mismatched or invalid acquirer in PARES 1047 Buyer Authentication Service Validate Authentication failed Mismatched or invalid Merchant ID in PARES 1048 Buyer Authentication Service Validate Authentication failed Mismatched or invalid card number in PARES 1049 Buyer Authentication Service Validate Authentication failed Mismatched or invalid currency code in PARES 1050 Buyer Authentication Service Validate Authentication failed Mismatched
94. sists of the following comments which correspond to the circled numbers in Figure 2 1 The comments pertain specifically to setting up a billing agreement and obtaining a BAID 1 When the buyer chooses to set up a billing agreement call the Set Express Checkout request ACTION S and pass the following information about the agreement The billing type required A description of the goods or services associated with the agreement optional The type of PayPal payment you require optional A string for your use in any way optional PayPal returns a TOKEN that you use in subsequent steps After the buyer clicks the PayPal button and you submit the Set Express Checkout request you will want to automatically direct your buyer to the PayPal website to log in or set up a Express Checkout for Payflow Billing Agreements and Reference Transactions Obtaining the BAID With Express Checkout Purchase PayPal account The redirect URL for this is shown below TOKEN is the value returned the Set Express Checkout response https www paypal com cgi bin webscr cmd _express checkout amp token lt TOKEN gt When the buyer logs in the buyer is presented with a PayPal Review page such as the example page shown in Figure 2 2 FIGURE 2 2 PayPal Review page Miata Auto Service Review Your Purchase and Billing Information PayPal 8 Secure Payments Payment For This is the description of the
95. ssed back in transactions see Chapter 4 Transaction Responses The TOKEN value returned associates this buyer with this particular Express Checkout flow Redirecting the Buyer to PayPal After your buyer clicks the PayPal button and you submit the Set Express Checkout request you will want to automatically direct your buyer to the PayPal website The redirect URL for this is https www paypal com cgi bin webscr cmd _express checkout amp token lt TOKEN gt TOKEN is the value returned in the Set Express Checkout response Norte Express Checkout has a variation on this redirect URL called useraction that allows you to bypass the call to Get Express Checkout Details and to change the text of the button displayed on the PayPal website from Continue to Pay Now For more information see Eliminating Your Order Review Page on page 17 PayPal recommends that you use the HTTPS response 302 Object Moved with your URL as the value of the Location header in the HTTPS response Alternately you can generate a web page for your buyer that includes a META REFRESH tag in the header An example is shown Express Checkout for Payflow 13 14 Express Checkout Processing Flow Express Checkout Sale Transaction Example below Remember to replace lt TOKEN gt with the token value that you received in the Set Express Checkout response The following example uses the META REFRESH tag lt html gt lt head gt lt
96. t magazine issue the billing agreement authorizes you to start charging the buyer s PayPal account on the agreed upon recurring basis without having the buyer log in to PayPal The following pages describe ways to obtain a BAID e Obtaining the BAID With Express Checkout Purchase on page 21 e Obtaining the BAID Without Express Checkout Purchase on page 25 Obtaining the BAID With Express Checkout Purchase To set up the billing agreement and obtain the BAID when the buyer makes an Express Checkout purchase from your website you need only provide additional parameters and values in the Express Checkout calls Figure 2 1 summarizes the flow Express Checkout for Payflow 21 22 Billing Agreements and Reference Transactions Obtaining the BAID With Express Checkout Purchase FIGURE 2 1 Obtaining the BAID with Express Checkout purchase Merchant website G n Request Y gt Set Express Checkout API ACTION S BILLINGTYPE MerchantinitiatedBilling Server 2 4 TTY Response Token PayPal Login L HTTP G wv Redirect RetumURL Token G mam 5 Confirm Order Request Token API Get Express Checkout Details Server ACTION 4 Response 6 Request Final Transaction Details API Thank Do Express Checkout Payment Server You 00 ACTION D 7 t Response Results BAID The message flow con
97. t performs the actual money transfer This guide refers to this request sequence and the resulting buyer experience as the Express Checkout flow Express Checkout for Payflow 11 Express Checkout Processing Flow Express Checkout Sale Transaction Example Express Checkout ACTION Values To identify each request in the Express Checkout flow you pass the appropriate ACTION parameter The table below shows the value of ACTION for each Express Checkout request TABLE 1 1 ACTION values for Express Checkout Request ACTION value Set Express Checkout ACTION S Get Express Checkout Details ACTION G Do Express Checkout Payment ACTION D Express Checkout Token The TOKEN value returned the response to Set Express Checkout associates the buyer with this particular Express Checkout flow You pass it back to the server in these Express Checkout requests e Inthe HTTP request to redirect the buyer s browser to the PayPal web site e In the Get Express Checkout Details request to obtain the buyer s shipping information e Inthe Do Express Checkout Payment request to carry out the transaction Express Checkout Sale Transaction Example This section describes the Express Checkout flow in greater detail using a Sale transaction as the example See Appendix A Express Checkout Parameter Reference for detailed descriptions of all required and optional Express Checkout transaction parameters e Set Express Checkout ACTION S e
98. the following e Back orders in which you send available merchandise immediately and the remaining merchandise as it is available e Split orders in which you send merchandise in more than one shipment perhaps to different addresses and you want to collect a payment for each shipment e Drop shipments or shipments from other vendors for which you accept the payment To create multiple authorizations of the Order over the 29 day period use the Do Authorization transaction Each Do Authorization places the buyer s funds on hold for up to three days If the three day honor period or the valid authorization period expires simply create another Do Authorization To set up an Order 1 Set TRXTYPES O in the Set Express Checkout Get Express Checkout Details Do Express Checkout Payment requests in your Express Checkout flow Express Checkout for Payflow 35 8 Express Checkout Transaction Types Do Reauthorization Set Express Checkout request TRXTYPE O ACTION S Get Express Checkout Details request optional ACTION G Do Express Checkout Payment request ACTION D 2 Note the value of PNREF in the Do Express Checkout Payment response for example RESULT 0 amp PNREF EFHP0CDBF5C7 amp RESPMSG Approved amp TOKEN EC 17C76533PL706494P amp PAYERID FHY4JXY7CV9PG amp PPREF 2P599077L3553652G To capture an Order you must first authorize it 1 To authorize the Order set
99. tion Types Order transaction instead of an Authorization Orders provide greater flexibility with fewer time constraints when handling products or services that not immediately available An Authorization uses the same parameters as a Sale transaction except that TRXTYPE is A See Express Checkout Sale Transaction Example for details To set up an Authorization set these parameters in the Set Express Checkout Get Express Checkout Details and Do Express Checkout Payment requests e Set Express Checkout request TRXTYPE A ACTION S e Get Express Checkout Details request optional TRXTYPE A ACTION G e Do Express Checkout Payment request ACTION D Note the value of PNREF in the Do Express Checkout Payment response for example RESULT 0 amp PNREF EFHPOCDBF5C7 amp RESPMSG Approved amp TOKEN EC 17C76533PL706494P amp PAYERID FHY4J0XY7CV9PG amp PPREF 2P599077L3553652G To capture authorized funds you use the PNREF to reference the original Authorization transaction See Delayed Capture for details Order An Order transaction represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days Orders provide you with greater flexibility in delivering merchandise than Authorizations You should use an Order when a Sale or an Authorization with a single Do Reauthorization do not meet your needs Situations in which Orders are appropriate include the handling of
100. uthorization or Do Reauthorization transaction response e Set TRXTYPE D This is an example Delayed Capture request with required parameters TRXTYPE D amp TENDER P amp PARTNER partner amp USER user amp VENDOR vendor amp PWD pwd amp ORIGID EFHPOCDBF5C7 Partial Capture To set up a partial capture of authorized funds pass the following parameters in the Delayed Capture request string e Set ORIGID PNREF PNREF value returned in the original Authorization Do Authorization or Do Reauthorization transaction response e Set TRXTYPE D e Set the value for AMT Set CAPTURECOMPLETES N to perform partial capture set CAPTURECOMPLETE Y to void any remaining amount of the original authorized transaction This example is based on an initial Authorization for 100 You charge 66 for the first partial shipment using a Delayed Capture transaction You charge the 34 for the final part of the shipment using a second Delayed Capture transaction 1 Capture the authorized funds for a partial shipment of 66 TRXTYPE D amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPal VENDOR SuperMerchant USER SuperMerchant amp CAPTURECOMPLETE N SORIGID EFHP0D426A51 amp 66 00 2 Once you have shipped the remainder of the merchandise capture the 34 balance TRXTYPE D amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPal amp VENDOR SuperMerce hant SUSER SuperMerchant amp CAPTURECOMPLETE Y amp ORIGID EFHP0D426A5
101. ves the right to make changes to any information herein without further notice Preface Chapter Contents 7 Intended 7 Related Documentation 7 How to Contact Customer 7 Document HIStory us s somis a 444 7 1 Express Checkout Processing Flow 9 What Is Express 2 9 How Express Checkout 0 9 Express Checkout Flow 11 Express Checkout ACTION 12 Express Checkout Token 12 Express Checkout Sale Transaction 12 Set Express Checkout 5 12 Redirecting the Buyer to PayPal 13 Get Express Checkout Details ACTION G 14 Redirecting the Buyer to Your Website 15 Do Express Checkout Payment 15 Other Express Checkout Concepts 16 Obtaining the Buyer s Telephone Number During Checkout 16 Eliminating Your Order Review Page 17 Pending 17 Ch
102. x Currency Codes Optional Description of items the buyer is purchasing Limitations 127 character alphanumeric string Optional Free form field for your own use such as a tracking number or other value you want PayPal to return in the Get Express Checkout Details response Limitations 256 character alphanumeric string Optional Merchant invoice number If you do not provide an invoice number the transaction ID PNREF will be submitted Limitations Nine character alphanumeric string Optional Identification code for use by third party applications to identify transactions Limitations 32 alphanumeric characters Optional Your URL for receiving Instant Payment Notification IPN about this transaction If you do not specify NotifyURL in the request the notification URL from your Merchant Profile is used if one exists Limitations 2048 alphanumeric characters Optional Line item name Character length and limitations 36 alphanumeric characters Optional Line item description for each different item purchased such as hiking boots or cooking utensils Limitations 35 character string Express Checkout for Payflow Express Checkout Parameter Reference A Reference Transaction Parameter Descriptions TABLE A 23 Reference Transaction Request Parameters Parameter Description L COSTn Optional Line item unit price The line item unit price can be a positive or a negative va

PayPal Express Checkout - 2013 Payflow Pro Guide

Contents

Download Pdf Manuals

Related Search

Related Contents