Home

PayPal Website Payments Pro - 2007 Developer's Guide

Contents

1. 42 4 Website Payments Pro Developer s Guide Chapter Chapter Chapter Chapter Contents 5 Testing Credit Card Transactions 43 Testing lt 43 Credit Card Numbers Used for Testing 43 Testing Result Code lt 44 6 PayPal Express Checkout Transaction Processing 47 What Is PayPal Express 47 How PayPal Express Checkout Works 48 Sale and Authorisation 49 Void Delayed Capture and Credit 50 PayPal Express Checkout Sale Transaction Example 50 Set Express Checkout 50 Redirecting the Customer to 51 Get Express Checkout Details 52 Redirecting the Customer to Your Website Example 52 Do Express Checkout Payment ACTION D 53 PayPal Express Checkout Transaction Parameter Descriptions 53 Sale and Authorisation Transaction Parameters 53 Void Transaction Parameters 62 Delayed Capture Transaction 62 Credit
2. 15 Connection 16 Values Required by All Transaction 17 Sale Transaction 18 Typical Sale Transaction PARMLIST 18 How to Format a Transaction 19 Website Payments Pro Developer s Guide ET Contents Chapter 4 Performing Direct Payment Credit Card Transactions 21 How Direct Payment Works lll lees 22 About Direct Payment Credit Card Processing 22 Considerations Regarding Your Website Integration 23 Parameters Used in 5 23 Additional Parameters by Transaction Type 29 Submitting Sale Transactions 29 When to Use a Sale Transaction 30 Additional Parameters for Sale 5 30 Typical Sale Transaction Parameter String 30 Submitting Authorisation Delayed Capture Transactions 31 Required Authorisation Transaction Parameters 31 Typical Authorisation Transaction Parameter 5 0 31 Required Delayed Capture Transaction Parameters 32 Delayed Capture Transaction Capturing Transactions for Lower
3. Table5 3 shows amounts that return specific PayPal result codes TABLE 5 3 Obtaining PayPal result code Result Definition 0 Approved 3 Invalid transaction type 4 Invalid amount 5 Invalid merchant information How to test using Website Payments Pro Payflow Edition Use an AMOUNT of 10000 or less Use the AMOUNT 10402 Use any of these as AMOUNT 10400 10401 10403 10414 Use any of these as AMOUNT 10548 10549 44 Website Payments Pro Developer s Guide Testing Credit Card Transactions Bl Testing Result Code Responses TABLE 5 3 Obtaining PayPal result code Continued Result Definition How to test using Website Payments Pro Payflow Edition 7 Field format error Use any of these as AMOUNT 10405 10406 10407 10408 10409 10410 10412 10413 10416 10419 10420 10421 10509 10512 10513 10514 10515 10516 10517 10518 10540 10542 12 Declined Use any of these as AMOUNT 10417 15002 15005 10506 10528 10539 10544 10545 10546 13 Referral Use the AMOUNT 10422 Website Payments Pro Developer s Guide 45 ES Testing Credit Card Transactions Testing Result Code Responses TABLE 5 3 Obtaining PayPal result code Continued Result Definition How to test using Website Payments Pro Payflow Edition 23 Invalid account number Use any of these as AMOUNT 10519 10521 10522 10527 10535 10541 10543 24 Invalid expiry date Use any of these as AMOUNT 10502 10508 30 Duplicate Transaction Use
4. For testing purposes only 0 01 will be submitted Continue Shopping Proceed to Checkout Get i 1 Get history log 2 PayPal as Payment Method HE DesignerFotos Billing Information Please select a payment method enter your billing address then click the Continue button Payment Method Save time Checkout securely without sharing your financial information o EE SS 25 a Gredit or Debit Gard Information Credit Card Type Selecta Card You can choose from several design variations for PayPal as a Payment Method See Payment Method Page Layout Recommendations 66 Website Payments Pro Developer s Guide PayPal Button Placement and Page Designs Payment Method Page Layout Recommendations Payment Method Page Layout Recommendations When you display the PayPal Acceptance Mark with other payment methods you have several designs to choose from e Asa radio button e As horizontal fields e Inapulldown SELECT list IMPORTANT Do not preselect any payment method Allow the customer to make a choice without any default As a radio button FIGURE 7 1 Payment ds PayPal as Unique Choice EE DesignerFotos Billing Information Please select a payment method enter your billing address then click the Continue button Payment Method paypar Save time Checkout securely Pay without sharing your financial information EEE Credit or Debit Card
5. PayPal Website Payments Pro Developer s Guide For Professional Use Only Currently only available in English A usage Professional Uniquement Disponible en Anglais uniquement pour l instant Last Updated March 2007 Website Payments Pro Developer s Guide 2006 PayPal Inc All rights reserved PayPal the PayPal logo Payflow and Payflow Pro are registered trademarks 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 PayPal Europe Ltd is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution PayPal FSA Register Number 226056 Notice of Non Liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice PayPal Inc does not guarantee that the fe
6. 2 PayPal as a Payment Method TABLE 7 1 PayPal Button Placement and Rules Placement PayPal Button Graphic Requirements Place the PayPal Checkout button on your cart page aligned with any other checkout buttons PayPalas a 1 Checkout Choice Fast easy secure Place the PayPal Acceptance Mark graphic 1 On your Payment Billing page PayPal 2 On your home page along with credit card logos Method if applicable HTML for PayPal Button Graphics You can get HTML for the PayPal Express Checkout button and PayPal Acceptance Mark from the following location https www paypal com express checkout buttons IMPORTANT Rather than storing the button graphics on your own server use the PayPal provided image paths for the graphics to reassure your customers that the checkout is secure and that you are displaying the most up to date logos from PayPal Website Payments Pro Developer s Guide 65 PayPal Button Placement and Page Designs Examples of Button Placement Examples of Button Placement Here are some examples of proper placement 1 PayPal as Checkout Choice and as Payment Method Views Cart My Help DesignerFotos PayPal s sample integration seri A demonstration of PayPal s integration flow Shopping Cart le E Qty Items Price San Francisco Bay 32 x 32 250 00 DEHE Mount Hamilton 24 x 15 50 00 pelete Subtotal 300 00
7. Issuing bank timed out Issuing bank unavailable Reauth error Order error PIM Adapter Unavailable PIM Adapter stream error PIM Adapter Timeout Cybercash Batch Error Cybercash Query Error Generic host error This is a generic message returned by your credit card processor The RESPMSG will contain more information describing the error Buyer Authentication Service unavailable Buyer Authentication Service Transaction timeout Buyer Authentication Service Invalid client version Buyer Authentication Service Invalid timeout value Buyer Authentication Service unavailable Buyer Authentication Service unavailable Buyer Authentication Service unavailable Buyer Authentication Service Merchant is not enrolled for Buyer Authentication Service 3 D Secure Buyer Authentication Service 3 D Secure error response received Instead of receiving a PARes response to a Validate Authentication transaction an error response was received 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 Buyer Authentication Service Invalid card type Buyer Authentication Service Invalid or missing currency code Buyer Authentication Service merchant status for 3D secure is invalid Website Payments Pro Developer s Guide Responses to Transaction Requests 8 RESULT Codes and RESPMSG Values TABLE 8
8. the transaction was approved Any other number indicates a decline or error RESULT codes are described in RESULT Codes and RESPMSG Values on page 74 Result of the card security code CVV2 check The issuing bank may decline the transaction if there is a mismatch In other cases the transaction may be approved despite a mismatch Type Length Alphanumeric 12 Numeric Variable Alpha 1 Y N X or no response For details on PayPal specific responses also see Card Security Code Results in this chapter Website Payments Pro Developer s Guide 69 70 Responses to Transaction Requests Contents of a Transaction Response TABLE 8 1 Transaction response values Continued Field PPREF RESPMSG AVSADDR AVSZIP PROCAVS PROCCVV2 Description Unique transaction ID of the payment Ifthe TRXTYPE ofthe request is A then you will need the value of PPREF for use with Authorisation and Delayed Capture transactions The response message returned with the transaction result Exact wording varies Sometimes a colon appears after the initial RESPMSG followed by more detailed information Response messages are described in RESULT Codes and RESPMSG Values on page 74 AVS address responses are for advice only This process does not affect the outcome of the authorisation See Using Address Verification Service on page 39 For details on PayPal specific responses also see Addre
9. voy ACTION D 7 4 Response Transaction Results Success Failure Figure 6 1 shows a typical set of web pages representing your merchant website The PayPal logo is used by the customer to choose PayPal as their method of payment PayPal Express Checkout gives you the flexibility to put this PayPal button graphic first in your checkout process or on your billing page with other payment options These guidelines are discussed in detail in Chapter 7 PayPal Button Placement and Page Designs 48 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing 6e Sale and Authorisation Transactions The web page layout may differ somewhat from your own web design but the points at which the PayPal Express Checkout API calls are made and when the customer is redirected to PayPal and back to your website are important to understand The events that take place at each numbered step in the figure are described below 1 On your website when your customer chooses to pay with PayPal you submit a Set Express Checkout request 2 The server sends back a token a string value to track your customer throughout the checkout process 3 You direct your customer to the PayPal site where they log in select a funding source and confirm contact and postal information PayPal Express Checkout includes parameters that you can use to customise the PayPal pages so they match characteristics of your own website
10. 54 S Sale transaction type 29 security AVS 39 Set Express Checkout request 50 SHIP TO Address parameters 28 29 SHIPTOBUSINESS parameter 57 SHIPTOCITY parameter 28 SHIPTOCOUNTRY parameter 28 SHIPTOCOUNTRYCODE parameter 58 SHIPTOSTATE parameter 28 SHIPTOSTREET parameter 28 57 SHIPTOSTREET2 parameter 57 SHIPTOZIP parameter 28 shopfront testing 43 Solo 25 STATE parameter 24 storing credit card numbers 23 STREET parameter 24 Switch 25 Website Payments Pro Developer s Guide T Z TAXAMT parameter 29 60 61 ZIP parameter 25 TENDER parameter 18 testing operation 43 testing Website Payments Pro Payflow Edition transactions 12 TOKEN parameter 54 56 57 59 60 transaction response PNREF parameter 73 RESPMSG parameter 74 RESULT parameter 74 transactions commercial card 39 creating 17 29 Sale 29 void 36 TRXTYPE parameter 18 U USER parameter 17 using Authorisation Delayed Capture transactions 31 using AVS 39 using credit transactions 35 using Delayed Capture transactions 33 using reference transactions 37 using Sale transactions 30 using void transactions 36 V VENDOR parameter 17 VERBOSITY changing setting 85 setting on per transaction basis 85 settings 83 VERBOSITY parameter 29 83 void transaction type 36 website integration considerations 23 Website Payments Pro library formats 13 software formats 13 Website Payments Pro Developer s Guide 97 98 Website Payments Pro Deve
11. DOMINICAN REPUBLIC EAST TIMOR ECUADOR Code BO BA BW BR VG BN BG BF CM CA CV KY CL CN CO CK CR CI HR CY CZ DK DJ DM DO TP EC Website Payments Pro Developer s Guide ISO Country Codes TABLE 1 Country codes Country Code EGYPT EG EL SALVADOR SV ESTONIA EE FIJI FJ FINLAND FI FRANCE FR FRENCH GUIANA GF FRENCH POLYNESIA PF GABON GA GEORGIA GE GERMANY DE GHANA GH GIBRALTAR GI GREECE GR GRENADA GD GUADELOUPE GP GUAM GU GUATEMALA GT GUINEA GN GUYANA GY HAITI HT HONDURAS HN HONG KONG HK HUNGARY HU ICELAND IS INDIA IN INDONESIA ID IRELAND IE Website Payments Pro Developer s Guide 89 ae ISO Country Codes 90 TABLE B 1 Country codes Country ISRAEL ITALY JAMAICA JAPAN JORDAN KAZAKHSTAN KENYA KUWAIT LAO PEOPLE S DEMOCRATIC REPUBLIC LATVIA LEBANON LESOTHO LITHUANIA LUXEMBOURG MACAO MACEDONIA MADAGASCAR MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITIUS MEXICO MICRONESIA FEDERATED STATES OF MOLDOVA MONGOLIA Code IL IT JM JP 5 E LA LV LB LS LT LU MO MK MG MY MV ML MT MH MQ MU MX FM MD MN Website Payments Pro Developer s Guide ISO Country Codes TABLE 1 Country codes Country Code MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ NAMIBIA NA NEPAL NP NETHERLANDS NL NETHERLANDS ANTILLES AN NEW ZEALAND NZ NICARAGUA NI NORTHERN MARIANA ISLANDS MP NORWAY NO OM
12. Express Checkout works like other Website Payments Pro features You submit transaction information to the server as name value pair parameter strings Note This chapter assumes that you are familiar with the following e The basic transaction parameters required in all Website Payments Pro transactions as described in Chapter 3 Creating a Simple Transaction Request e The parameters for each transaction type as described in Chapter 4 Performing Direct Payment Credit Card Transactions Website Payments Pro Developer s Guide 47 BEI PayPal Express Checkout Transaction Processing How PayPal Express Checkout Works How PayPal Express Checkout Works Figure 6 1 summarises the PayPal Express Checkout process FIGURE 6 1 Customer checkout sequence Merchant website a Request _ Set Express Checkout API 8 ACTION S Server 2 4 Response Token PayPal Login L HTTP Redirect gt https www paypal com cgi bin webscr cmd _express checkout amp token EC 30522678F3934250X amp Example token value a HTTP Redirect Confirm Details ReturnURL Token Continue 9 Confirm funding 5 source and address Confirm Order Request Token Get Express Checkout Details ACTION G Pay 4 Response Shipping Address Telephone Number 6 Request Final Transaction Details _ 1 Thank Do Express Checkout Payment Server
13. For example you can provide your own logo and colours These parameters are described in Set Express Checkout Request Parameters on page 53 4 When your customer clicks the Continue button PayPal sends them 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 customer 5 Optionally you can send the Get Express Checkout Details request to obtain details about your customer such as the customer s telephone number and postal address You send the token to identify the customer The server returns the requested information 6 When your customer clicks the Pay button you submit the Do Express Checkout Payment request to perform the actual payment transaction The server returns the transaction result Sale and Authorisation Transactions PayPal Express Checkout Sale and Authorisation transactions are handled a little differently than described in Chapter 4 Performing Direct Payment Credit Card Transactions Unlike a Direct Payment credit card Sale or Authorisation transaction request which is submitted as a single request a PayPal Express Checkout Sale or Authorisation requires that you submit at least two requests e Set Express Checkout e Do Express Checkout A third request Get Express Checkout Details is optional Do Express Checkout performs the actual money transfer The Set Express Checkout and Get Express Checkout De
14. If CAPTURECOMPLETE is y any remaining amount of the original reauthorised transaction 15 automatically voided Required No No but is recom mended No No No Type String Alpha numeric Numeric Numeric String Alpha numeric Alpha numeric Alpha numeric Max Length 20 32 15 128 128 12 Website Payments Pro Developer s Guide 25 26 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4 1 Transaction parameters Continued Parameter CURRENCY CUSTOM CUSTREF CVV2 EMAIL EXPDATE FREIGHTAMT Description One of the following three character currency codes e USD US dollar EUR Euro GBP UK pound CAD Canadian dollar JPY Japanese Yen AUD Australian dollar A free form field for your own use Merchant defined identifier for reporting and auditing purposes For example you can set CUSTREF to INVNUM A three of four digit code that is printed not imprinted on the back of a credit card Used as partial assurance that the card is in the buyer s possession For details see Security Code Validation on page 40 NOTE CVV2 values are normalised to Y and X values The PayPal processor values are returned when you set VERBOSITY parameter to MEDIUM For details on VERBOSITY see Appendix A Verbosity Viewing Processor Specific Transaction Results Email address of payer
15. Information Credit Card Type Select Card v As horizontal option fields FIGURE 7 2 Payment Methods Horizontal Design Payment Method O m7 As pulldown SELECT list FIGURE 7 3 Payment Methods Pulldown SELECT List Payment Method Select one PayPal visa Master Card American Express Website Payments Pro Developer s Guide 67 PayPal Button Placement and Page Designs Payment Method Page Layout Recommendations 68 Website Payments Pro Developer s Guide Responses to Transaction Requests This chapter describes the contents of a response to a transaction request When a transaction finishes the Payflow server returns a response string made up of name value pairs For example this is a response to a credit card Sale transaction request RESULT O amp PNREF VXYZ01234567 amp RESPMSG APPROVED amp AUTHCODE 123456 amp AVSADDR Y amp AVSZIP N amp IAVS Y amp CVV2MATCH Y Contents of Transaction Response All transaction responses include values for RESULT PNREF and RESPMSG Values for AVSADDR and AVSZIP are included if you use AVS Table 8 1 describes the values returned in response string TABLE 8 1 Transaction response values Field PNREF RESULT CVV2MATCH Description Reference ID unique number that identifies the transaction PNREF is described in PNREF Format on page 73 The outcome of the attempted transaction A result of 0 zero indicates
16. Rules Website Payments Pro must be integrated on your website in the following ways You must e Present the PayPal Express Checkout button and associated messaging before requesting postal address billing address and financial information PayPal account holders should not be required to enter any of this information on your website because the information is available from their PayPal accounts e Display PayPal as an option together with other payment methods wherever other payment methods are offered e Present the PayPal mark graphic wherever other payment marks are displayed For details on displaying PayPal graphics on your website see Chapter 7 Integrating PayPal Button Graphics Testin g For details on testing see the documentation at the following URL https test expresscheckout paypal com documentation About the PayPal SDK The SDK is available from the PayPal Manager Downloads page Website Payments Pro Developer s Guide Installing and Configuring the Payflow SDK The Payflow SDK is available either as standalone client that you can integrate with your web shop using CGI scripts or as a set of APIs for direct integration with your application This chapter provides instructions for downloading the SDK appropriate to your platform IMPORTANT Full API documentation is included with each SDK Supported Platforms The PayPal SDK is available on all major web server platforms in a variety
17. Sale Transaction PARMLIST The following is a typical PARMLIST string passed in a Sale transaction TRXTYPE S amp TENDER C amp USER SuperMerchant amp PWD SuperUserPassword amp PARTNER PayPal UK amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT1 Reservation amp FIRSTN AME JOhn amp LASTNAME Jones amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CLIENTIP 0 0 0 0 Note that besides the required Sale transaction parameters this string includes other typical Website Payments Pro Payflow Edition parameters These parameters are described in Chapter 4 Performing Direct Payment Credit Card Transactions and in Chapter 6 PayPal Express Checkout Transaction Processing Website Payments Pro Developer s Guide Creating a Simple Transaction Request I How to Format a Transaction How to Format a Transaction For details on how to format a transaction based on the above information refer to the examples and the supporting documentation provided with your SDK Website Payments Pro Developer s Guide 19 Creating a Simple Transaction Request How to Format a Transaction 20 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions This chapter provides guidelines on how to implement PayPal Direct Payment transactions Direct Payment offers you credit card payment processing capability through PayPal directly from the buyer s cr
18. Website Payments Pro Developer s Guide 53 0 PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions e The following optional request parameters listed below CURRENCY EMAIL ORDERDESC INVNUM SHIPTOSTREET SHIPTOCITY SHIPTOCOUNTRY SHIPTOSTATE SHIPTOZIP e The parameters and described in Table 6 2 TABLE 6 2 Set Express Checkout request parameters Parameter Name Description Type TOKEN Include this parameter to modify an existing Saleor String Authorisation request The value 1s returned in a previous Set Express Checkout response MAXAMT The expected maximum total amount of the Decimal complete order including postage and tax charges CUSTOM Free form field for your own use such asa tracking Alpha number or other value you want PayPal to return In numeric the Get Express Checkout Details response RETURNURL URL to which the customer s browser is returned String after choosing to pay with PayPal NoTE PayPal recommends that the value of RETURNURL be the final review page on which the customer confirms the order and payment CANCELURL URL to which the customer is returned if the String customer does not approve the use of PayPal to pay you NoTE PayPal recommends that the value of CANCELURL be the original page on which the customer chose to pay with PayPal REQCONFIRMSHIPPING IslorO The value 1 indicates that you require that String the customer s postal
19. addition to the response parameters described in Chapter 8 Responses to Transaction Requests the following PAYMENTTYPE parameter can be returned in PayPal Express Checkout Delayed Capture responses TABLE 6 10 Delayed Capture transaction response parameters Max Parameter Name Description Type Length PAYMENTTYPE Returns instant if the payment is instant or String 7 eCheque if the payment is delayed Credit Transaction Parameters In addition to the parameters required by all transaction types described in Chapter 3 Creating a Simple Transaction Request and the parameters described in Table 4 1 Transaction parameters the following MEMO parameter can be used in PayPal Express Checkout Credit transactions Note PayPal Express Checkout only supports reference transactions for Credits TABLE 6 11 Credit transaction request parameters Max Parameter Name Description Required Type Length MEMO Custom memo about the credit No Alphanumeric 255 Website Payments Pro Developer s Guide 63 BEI PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions 64 Website Payments Pro Developer s Guide PayPal Button Placement and Page Designs IMPORTANT When you offer PayPal Express Checkout to your customers you are required to display it in two forms for your customers best buying experience 1 PayPal as a Checkout Choice on your shopping cart page
20. address on file with PayPal be a confirmed address Setting this element overrides the setting you have specified in your Merchant Account Profile Max Length 20 256 No max length No max length 54 Website Payments Pro Developer s Guide TABLE 6 2 PayPal Express Checkout Transaction Processing e PayPal Express Checkout Transaction Parameter Descriptions Set Express Checkout request parameters Continued Parameter Name NOSHIPPING ADDROVERRIDE LOCALECODE PAGESTYLE HDRIMG HDRBORDERCOLOR Description Is 1 or 0 The value 1 indicates that on the PayPal pages no postal address fields should be displayed whatsoever Is 1 or 0 The value 1 indicates that the PayPal pages should display the postal address set by you in the postal address SHIPTO parameters passed to this Set Express Checkout request not the postal address on file with PayPal for this customer Displaying the PayPal postal address on file does not allow the customer to edit that address Locale of pages displayed by PayPal during PayPal Express Checkout Sets the Custom Payment Page Style for payment pages associated with this button link PageStyle corresponds to the HTML variable page style for customising 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 A URL for the image you want to appe
21. credit card processing The chapter provides a basic set of data parameters typically used in transaction requests e Chapter 5 Testing Credit Card Transactions Website Payments Pro Developer s Guide Preface Where to Go for More Information e Chapter 6 PayPal Express Checkout Transaction Processing explains how PayPal Express Checkout works and describes additional optional parameters you can send in PayPal Express Checkout transaction requests e Chapter 7 PayPal Button Placement and Page Designs e Chapter 8 Responses to Transaction Requests describes parameters returned in transaction responses e Appendix A Verbosity Viewing Processor Specific Transaction Results describes how you can use the VERBOSITY parameter to control the kind and level of information you want returned in a transaction response e Appendix ISO Country Codes lists the country codes you provide as transaction data in certain transactions Where to Go for More Information PayPal Manager Online Help describes the use of PayPal Manager the web based administration tool that you can use to process transactions manually issue credits and generate reports PayPal Manager provides links to the PayPal website where you can perform additional tasks such as resolving disputes See the Manager Online Help for details Getting Started with PayPal Manager contains instructions on how to use PayPal Manager including te
22. have special meanings in the PARMLIST name value pairs like the following examples are not valid NAME Ruff amp Johnson COMMENT1 Level 5 To use special characters in the value of name value pair use length tag The length tag specifies the exact number of characters and spaces that appear in the value The following name value pairs are valid NAME 14 Ruff amp Johnson COMMENTI 7 Level 5 99 Quotation marks are not allowed even if you use a length tag Values Required by All Transaction Types All Payflow SDK transactions require the parameters described in Table 3 2 TABLE 3 2 Required transaction parameters Max Parameter Description Required Type Length USER If you set up one or more additional users on the account Yes Alphanumeric 64 this value is the ID of the user authorised to process transactions If however you have not set up additional users on the account USER has the same value as VENDOR The examples in this document use USER SuperMerchant Limitations This value is case sensitive VENDOR Your merchant login ID that you created when you Yes Alphanumeric 64 registered for the Website Payments Pro account The examples in this document use VENDOR SuperMerchant Limitations This value is case sensitive PARTNER ID provided to you by the authorised PayPal Reseller Yes Alphanumeric 12 who registered you for the Payflow SDK If you purchased your accoun
23. of formats to support your integration requirements It is available as C library 11 binary executable Java library COM object Java Native Interface and Perl Module Interface TABLE 2 1 Supported platforms Windows NT 4 0 2000 2003 Linux libc6 glibc2 ELF kernels 2 0 36 and above Solaris 2 6 Intel Linux Redhat 9 x Solaris 2 7 2 8 Sparc Pure Java Any JDK 1 2 1 4 BSDI 4 0 SGI IRIX 6 2 HP UX 11 0 AIX 4 3 FreeBSD 5 x Website Payments Pro Developer s Guide 13 Ea Installing and Configuring the Payflow SDK Preparing the Payflow Client Application Preparing the Payflow Client Application Follow these steps to download and install Step 1 Download the Payflow SDK From the Download page in PayPal Manager https manager paypal com download the Payflow SDK appropriate for your platform Step 2 Extract the files to a local directory Step 3 Configure your firewall If you have a stateful firewall enable outbound traffic for SSL port 443 The firewall keeps state on the connection and automatically permits the inbound response from PayPal If you do not have a stateful firewall enable inbound and outbound traffic for SSL port 443 Outbound traffic permits the initial request by Website Payments Pro while inbound permits the response from PayPal Step4 Setthe certificate path To enable the client to authenticate the Payflow server you must set the path to include the certs direct
24. 5 Payflow transaction RESULT values and RESPMSG text Continued RESULT 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 RESPMSG and Explanation Buyer Authentication Service Validate Authentication failed missing or invalid PARES Buyer Authentication Service Validate Authentication failed PARES format is invalid Buyer Authentication Service Validate Authentication failed Cannot find successful Verify Enrolment Buyer Authentication Service Validate Authentication failed Signature validation failed for PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid amount in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid acquirer in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid Merchant ID in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid card number in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid currency code in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid XID in PARES Buyer Authentication Service Validate Authentication failed Mismatched or invalid order date in PARES Buyer Authentication Service Validate Authentication failed This PARES was already validated for a previous Validate
25. 66697a Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions me Submitting Authorisation Delayed Capture Transactions Submitting Authorisation Delayed Capture Transactions An Authorisation TRXTYPE A transaction places a hold on the cardholder s open to buy limit lowering the cardholder s limit by the amount of the transaction It does not transfer funds One or more Delayed Capture TRXTYPE D transactions are performed after an Authorisation to capture the original Authorisation amount You can perform up to ten partial captures for a single authorisation provided the buyer is in good standing A partial capture keeps the funds in a Pending status A Delayed Capture is scheduled for settlement during the next settlement period Because Visa and MasterCard regulations prohibit capturing credit card transaction funds until a product or service has been sent to the buyer most processing networks implement an Authorisation transaction followed by one or more Delayed Capture transactions When to Use Authorisation Delayed Capture Transactions If your business does not provide immediate fulfilment of products or services you should use this two stage transaction model also known as Delayed Capture processing because it enables you to capture credit card transaction funds when your are ready to collect them If your business provides immediate fulfilment you can use a simple Sale transaction ins
26. AN OM PAKISTAN PK PALAU PW PALESTINE PS PANAMA PA PAPUA NEW GUINEA PG PARAGUAY PY PERU PE PHILIPPINES REPUBLIC OF PH POLAND PL PORTUGAL PT PUERTO RICO PR QATAR QA ROMANIA RO RUSSIAN FEDERATION RU RWANDA RW SAINT KITTS AND NEVIS KN Website Payments Pro Developer s Guide 91 ae ISO Country Codes 92 TABLE B 1 Country codes Country SAINT LUCIA SAINT VINCENT AND THE GRENDINES SAMOA SAUDI ARABIA SENEGAL SERBIA AND MONTENEGRO SEYCHELLES SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOUTH AFRICA SOUTH KOREA SPAIN SRI LANKA SWAZILAND SWEDEN SWITZERLAND TAIWAN TANZANIA UNITED REPUBLIC OF THAILAND TOGO TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS Code LC VC WS SA SN CS SC SG SK SI SB ZA ES LK SZ SE CH TW TZ TH TG TO TT TN TR TM TC Website Payments Pro Developer s Guide ISO Country Codes TABLE 1 Country codes Country Code UGANDA UG UKRAINE UA UNITED ARAB EMIRATES AE UNITED KINGDOM GB UNITED STATES OF AMERICA US URUGUAY UY UZBEKISTAN UZ VANUATU VU VENEZUELA VE VIETNAM VN VIRGIN ISLANDS U S VI YEMEN ARAB REPUBLIC YE ZAMBIA ZM Website Payments Pro Developer s Guide 93 ae ISO Country Codes 94 Website Payments Pro Developer s Guide parameter 24 parameter 24 ACTION parameter 56 57 59 add on services Recurring Billing Service 12 Address 39 Addres
27. Amounts 33 Delayed Capture Transaction Capturing Transactions for Higher Amounts 34 Delayed Capture Transaction Error Handling and Retransmittal 2 35 Submitting Credit Transactions 000002 eee 35 Required Credit Transaction Parameters 35 Credit Transaction Parameter 5 0 5 35 Submitting Void Transactions 36 When to Use a Void Transaction 36 Required Void Transaction 36 Example Void Transaction Parameter String 37 Recharging to the Same Credit Card Reference Transactions 37 When to Use a Reference Transaction 37 Transaction Types that Can Be Used as the Original Transaction 38 Fields Copied from Reference 38 Example Reference 38 Using Address Verification Service 39 Example AVS Request Parameter 40 Example AVS Response 40 Card Security Code 40 American Express Card Security Code 41 Example CVV2 Request Parameter String 42 Example CVV2 lt
28. Authentication transaction Website Payments Pro Developer s Guide 79 Responses to Transaction Requests RESULT Codes and RESPMSG Values RESULT Values for Communications Errors value for RESULT less than zero indicates that communication error occurred In this case no transaction is attempted value of 1 or 2 usually indicates configuration error caused by an incorrect URL or by configuration issues with your firewall A value of 1 or 2 can also be possible if the PayPal servers are unavailable or an incorrect server socket pair has been specified value of 1 can also result when there are Internet connectivity errors Contact Customer Support regarding any other errors NoTe Details of the response message may vary slightly depending on your SDK integration TABLE 8 6 RESULT values for communications errors RESULT Description 1 Failed to connect to host 2 Failed to resolve hostname 5 Failed to initialise SSL context 6 Parameter list format error amp in name 7 Parameter list format error invalid name length clause 8 SSL failed to connect to host 9 SSL read failed 10 SSL write failed 11 Proxy authorisation failed 12 Timeout waiting for response 13 Select failure 14 Too many connections 15 Failed to set socket options 20 Proxy read failed 21 Proxy write failed 22 Failed to initialise SSL certificate 23 Host address not specified 24 Invalid transaction type 25
29. E Returns instant if the payment is instant String 7 or eCheque if the payment is delayed CORRELATIONID Value used for tracking this Direct Alphanumeric 13 Payment transaction Address Verification Responses from PayPal Table 8 2 Address verification response value mapping compares the detailed response returned by the PayPal processor for address verification to the normalised 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 For details on VERBOSITY see Appendix A Verbosity Viewing Processor Specific Transaction Results TABLE 8 2 Address verification response value mapping PayPal Processor AVSCode PayPal Processor AVSCode Meaning AVSADDR AVSZIP A Address Y B International A Y N C International N N N D International X Y Y E Not allowed for MOTO Internet Phone X X transactions F UK specific X Y Y Global Unavailable I International Unavailable Website Payments Pro Developer s Guide 71 0 Responses to Transaction Requests Card Security Code Results TABLE 8 2 Address verification response value mapping Continued PayPal Processor AVSCode PayPal Processor AVSCode Meaning AVSADDR AVSZIP N No N N P Postal International Z N Y R Retry X X S Service Not Supported
30. Expiry date of the credit card in mmyy format For example 0308 represents March 2008 Total postage costs for this order NoTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See the CURRENCY entry in this table for details Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be a period Do not use comma separators Use 1199 95 not 1 199 95 Required No Type Alpha Alpha numeric Alpha numeric Alpha numeric Alpha numeric Numeric Decimal Max Length 256 12 127 10 Website Payments Pro Developer s Guide TABLE 4 1 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions Transaction parameters Continued Parameter HANDLINGAMT INVNUM ITEMAMT L DESCn L AMTn L QTYn L TAXAMTn Description Required Type Total packing costs for this order No Decimal NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See the CURRENCY entry in this table for details Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be period Do not use comma separators Use 1199 95 not 1 199 95 Your own unique invoice or tracking number No Alpha numeric Sum of cost of all items in this order No Decimal Limi
31. Failed to create a socket 26 Failed to initialise socket layer 27 Parameter list format error invalid name length clause 80 Website Payments Pro Developer s Guide Responses to Transaction Requests RESULT Codes and RESPMSG Values TABLE 8 6 RESULT values for communications errors Continued RESULT Description 28 Parameter list format error name 29 Failed to initialise SSL connection 30 Invalid timeout value 31 The certificate chain did not validate no local certificate found 32 The certificate chain did not validate common name did not match URL 40 Unexpected Request ID found in request 41 Required Request ID not found in request 99 Out of memory 100 Parameter list cannot be empty 103 Context initialisation failed 104 Unexpected transaction state 105 Invalid name value pair request 106 Invalid response format 107 This XMLPay version is not supported 108 The server certificate chain did not validate 109 Unable to do logging 111 The following error occurred while initialising from message file lt Details of the error message gt 113 Unable to round and truncate the currency value simultaneously Website Payments Pro Developer s Guide 81 Responses to Transaction Requests RESULT Codes and RESPMSG Values 82 Website Payments Pro Developer s Guide Verbosity Viewing Processor Specific Transaction Results Transaction results especially values for declines and err
32. ID in PayPal Manager reports value returned from the original transaction For details on PNREF see Chapter 8 Responses to Transaction Requests In addition if the amount of the capture differs from the amount of the Authorisation you also must pass a value for AMT Fields Copied from the Authorisation Transaction into the Delayed Capture Transaction The following fields are copied from the Authorisation transaction into a Delayed Capture transaction if they exist in the original transaction If you provide a new value for any of these parameters when submitting the Delayed Capture transaction then the new value is used Exceptions are ACCT and EXPDATE These parameters retain their original values ACCT AMT CITY COMMENTI CLIENTIP COMMENT2 COUNTRY CUSTCODE EMAIL EXPDATE FIRSTNAME FREIGHTAMT INVNUM LASTNAME NOTE PHONENUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTO ZIP STATE STREET TAXAMT ZIP Step 1 Perform the Authorisation transaction The Authorisation transaction uses the same parameters as Sale transactions except that the transaction type is A The return data for an Authorisation transaction is the same as for a Sale transaction To capture the authorised funds perform a Delayed Capture transaction that includes the value returned for PNREF as described in Step 2 on page 33 EXAMPLE 4 4 Authorisation transaction parameter string Issue Authorisation only Transaction TRXT
33. Only your account administrator can enable reference transactions for your account If you attempt to perform a reference transaction in an account for which reference transactions are disallowed RESULT code 117 is returned See PayPal Manager online help for instructions on setting reference transactions and other security features Sale and Authorisation transactions can make use of a reference transaction as a source of transaction data PayPal looks up the reference transaction and copies its transaction data into the new Sale or Authorisation transaction IMPORTANT When PayPal looks up the reference transaction neither the transaction being referenced nor any other transaction in the database is changed in any way That is a reference transaction is a read only operation only the new transaction is populated with data and acted upon No linkage is maintained between the reference transaction and the new transaction You can also initiate reference transactions from PayPal Manager See PayPal Manager Online Help for details Website Payments Pro Developer s Guide 37 38 Performing Direct Payment Credit Card Transactions Recharging to the Same Credit Card Reference Transactions Transaction Types that Can Be Used as the Original Transaction You can reference any of the supported transaction types shown below to supply data for new Sale or Authorisation transaction e Sale e Authorisation To capture the funds for an ap
34. Referral Transaction cannot be approved electronically but can be approved with a verbal authorisation Contact your merchant bank to obtain an authorisation and submit a manual Voice Authorisation transaction 14 Invalid Client Certification ID Check the HTTP header If the tag X VPS VIT CLIENT CERTIFICATION ID is missing RESULT code 14 is returned 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 expiry 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 26 Invalid vendor account 27 Insufficient partner permissions 28 Insufficient user permissions 29 Invalid XML document This could be caused by an unrecognised XML tag or a bad XML format that cannot be parsed by the system 30 Duplicate transaction Website Payments Pro Developer s Guide 75 76 Responses to Transaction Requests RESULT Codes and RESPMSG Values TABLE 8 5 Payflow transaction RESULT values and RESPMSG text Continued RESULT 31 32 33 34 35 36 37 S0 51 99 100 101 102 103 104 105 106 107 108 109 110 111 112 RESPMSG and Explanation Error in adding the recurring profile Error in mo
35. Sale and Delayed Capture transactions To submit a Credit transaction you must pass the following parameter ORIGID Set the value of ORIGID to the PNREF value returned for the original transaction PNREF is displayed as the Transaction ID in PayPal Manager reports For details on PNREF see Chapter 8 Responses to Transaction Requests If you do not specify an amount then the amount of the original transaction is credited to the cardholder Fields Copied from the Original Transaction into the Credit Transaction The following fields are copied from the original transaction into the Credit transaction if they exist in the original transaction If you provide a new value for any of these parameters when submitting the Credit transaction then the new value is used Exceptions are ACCT and EXPDATE These parameters retain their original values Norte The TAXAMT and FREIGHTAMT parameters are not copied for referenced credits ACCT AMT CITY COMMENTI CLIENTIP COMMENT2 COUNTRY CUSTCODE EMAIL EXPDATE FIRSTNAME INVNUM LASTNAME SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET PHONENUM ZIP Credit Transaction Parameter Strings This is an example Credit transaction string TRXTYPE C amp TENDER C amp PARTNER PayPalUK amp VENDOR SuperMerchant amp USER SuperMerchan t amp PWD SuperUserPassword amp ORIGID EFHP0D426A62 Website Payments Pro Developer s Guide 35 Esca Performin
36. TREET SHIPTOZIP STATE STREET TAXAMT ZIP 36 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions ree Recharging to the Same Credit Card Reference Transactions Example Void Transaction Parameter String This is an example Void transaction parameter string EXAMPLE 4 12 Void transaction parameter string TRXTYPE V amp TENDER C amp PARTNER PayPalUK amp VENDOR SuperMerchant amp USER SuperMerchan t amp PWD SuperUserPassword amp ORIGID EFHP0D426A68 Recharging to the Same Credit Card Reference Transactions If you need to recharge a credit card and you are not storing the credit card information in your local database you can perform a reference transaction A reference transaction takes the existing credit card information that is on file and reuses it When to Use a Reference Transaction Say that Joe Smith purchases a holiday gift from your website shop and requests that it be sent by UPS ground service That evening Joe becomes concerned that the item might not arrive in time for the holiday So he calls you to upgrade postage to second day air You obtain his approval for charging an extra 10 for the upgrade In this situation you can create a reference transaction based on the original Sale and charge an additional 10 to Joe s credit card without having to ask him again for his credit card information CAUTION As a security measure reference transactions are disallowed by default
37. Table 6 3 TABLE 6 3 Set Express Checkout response parameters Parameter Name TOKEN Description A time stamped token by which you identify to PayPal that you are processing this payment with PayPal 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 Max Type Length String 20 56 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing e PayPal Express Checkout Transaction Parameter Descriptions Get Express Checkout Details Request Parameters Get Express Checkout Details request parameters are described in Table 6 4 TABLE 6 4 Get Express Checkout Details request parameters Max Parameter Name Description Required Type Length ACTION Is G to indicate this is a Get Express Yes Alpha 1 Checkout Details request TOKEN String value returned by the Set Yes String 20 Express Checkout response Get Express Checkout Details Response Parameters Get Express Checkout Details response parameters include RESULT and RESPMSG described in Chapter 8 Responses to Transaction Requests the parameters listed below and the parameters described in Table 6 5 EMAIL INVNUM SHIIPTOCITY SHIPTOCOUNTRY SHIPTOSTATE SHIPTOZIP TABLE 6 5 Get Express Checkout Details response parameters Max Parameter Name Description Type Length TOKEN String value r
38. Transaction Parameters 63 7 PayPal Button Placement and Page Designs 65 HTML for PayPal Button 65 Examples of Button Placement 66 Payment Method Page Layout Recommendations 67 8 Responses to Transaction Requests 69 Contents of a Transaction Response 69 Address Verification Responses from amp 71 Card Security Code 72 Normalised Results oa 2 4 24 A 72 PayPal Card Security Code lt 73 PNREF Value e g od usce oer ted ETL DOK GRASS VESENET ERE 73 PNREF Format e aa s s ss sss oss 73 Website Payments Pro Developer s Guide ET Contents RESULT Codes and RESPMSG Values RESULT Values for Transaction Declines or Errors RESULT Values for Communications Errors Appendix A Verbosity Viewing Processor Specific Transaction Results epi Supported Verbosity Settings Changing the Verbosity Setting Setting the Default Verbosity Level for All Transactions Setting the Verbosity Level on a Per Transaction Basis Appendix B ISO Country Codes Website Payments Pro Developer s Guide Preface Websit
39. Transactions on hold pending customer intervention DATE_TO SETTLE Date format 19 Value available only before settlement has started YY YY MM DD HH MM SS BATCHID Integer 10 Value available only after settlement has assigned a Batch ID SETTLE_DATE Date format 19 Value available only after settlement has completed YYYY MM DD HH MM SS 84 Website Payments Pro Developer s Guide Verbosity Viewing Processor Specific Transaction Results Changing the Verbosity Setting Table A 2 shows the increments that are possible on basic TRANSSTATE values TABLE A 2 TRANSSTATE increments Increment Meaning 100 No client acknowledgment ACK is received status 0 in V2 for example 106 is TRANSSTATE 6 Transactions in this range do not settle For transactions in TRANSSTATE 106 use Auto Resettle in PayPal Manager s Transaction Terminal to submit them for settlement or void them using a manual Void See PayPal Manager Online Help for details on using PayPal Manager 200 The host process never receives ACK from the transaction broker or backend payment server A transaction with a TRANSSTATE of 200 is basically in limbo and will not be settled 1000 Voided transactions Any TRANSSTATE of 1000 for example 1006 means the transaction was settle pending However it was voided either through the API PayPal Manager or PayPal Customer Service Changing the Verbosity Setting Setting the Default Verbosity Level for All Transa
40. V2 char 1 response from the PayPal processor PROCCARDSECURE char 1 VPAS SPA response from the PayPal processor ADDLMSGS char Up to 1048 Additional error message that indicates that the characters merchant used a feature that is disabled Typically 50 characters Website Payments Pro Developer s Guide 83 Verbosity Viewing Processor Specific Transaction Results Supported Verbosity Settings TABLE A 1 Verbosity settings Continued Field Name Type Length Description TRANSSTATE Integer 10 State of the transaction The values are 0 General succeed state 1 General error state 3 Authorisation approved 6 Settlement pending transaction is scheduled to be settled 7 Settlement in progress transaction involved in a currently ongoing settlement 8 Settled successfully 9 Authorisation captured once an authorisation type transaction is captured its TRANSSTATE becomes 9 10 Capture failed an error occurred while trying to capture an authorisation because the transaction was already captured 11 Failed to settle transactions fail settlement usually because of problems with the processor or because the card type is not set up with the processor 1 2 Unsettled transaction because of incorrect account information 14 For various reasons the batch containing this transaction failed settlement 15 Settlement incomplete due to a chargeback 106 Unknown Status Transaction Transactions not settled 206
41. X X U Unavailable X X W Whole Postcode N Y X Exact Match Y Y Y Yes Y Y Z Zip postcode N Y All other X X Card Security Code Results The CVV2MATCH parameter returns Y N or X or a PayPal processor specific response Normalised Results If you submit the transaction request parameter for card security code that is the CVV2 parameter the cardholder s bank returns a normalised Yes No response in the CVV2MATCH response parameter as described in Table 8 3 TABLE 8 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 72 Website Payments Pro Developer s Guide Responses to Transaction Requests PNREF Value PayPal Card Security Code Results Table 8 4 security code response code mapping 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 For details on VERBOSITY see Appendix A Verbosity Viewing Processor Specific Transaction Results TABLE 8 4 Card security code response code mapping PayPal Processor CVV2 PayPal Processor Code Code Description PROCVV2MATCH M Match Y No Match N P Not Processed X S Service Not Suppo
42. YPE A amp TENDER C amp USER SuperMerchant amp VENDOR SuperMerchant amp PARTNER PayPalU K amp PWD SuperUserPassword amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 9 O6COMMENT1 Reservation amp FIRSTNAME John amp LASTNAME Jones amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CLIENTIP 0 0 0 0 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions Submitting Authorisation Delayed Capture Transactions EXAMPLE 4 5 Authorisation response For details on response parameters see Chapter 8 Responses to Transaction Requests RESULT O amp PNREF EFHPOD426838 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATCH X amp PPREF 68W3371331353001F amp CORRELATIONID 2e52df7ddf292 Step2 Perform Delayed Capture transaction Set ORIGID to the PNREF value returned in the original Authorisation transaction response string There is no need to retransmit the credit card or billing address information it is stored at PayPal If the capture succeeds the amount of the Sale is transferred to the merchant s account during the daily settlement process If the capture does not succeed the hold on the cardholder s open to buy is still in effect EXAMPLE 4 6 Delayed Capture transaction parameter string TRXTYPE D amp TENDER C amp USER SuperMerchant amp VENDOR SuperMerchant PARTNER PayPalUK amp PWD SuperUserPassword amp TENDER C amp COMMENT1 Res
43. ansaction request to the Payflow server in either of two modes e Name value pair e XMLPay The examples in this guide are presented in name value pair format Name value pair syntax guidelines are described in PARMLIST Syntax Guidelines on page 16 XMLPay is an XML syntax for payment requests and associated responses in a payment processing network Instead of using name value pairs you can send to the Payflow server XML documents based on the XMLPay 2 0 schema For details on XMLPay see the Website Payments Pro XMLPay Developer s Guide It is available from the Documentation page in PayPal Manager Website Payments Pro Developer s Guide 15 16 Creating Simple Transaction Request Transaction Request Connection Parameters Table 3 1 describes the connection parameters Pass them in the format and syntax required by the Payflow SDK and programming language that you are using See your integration documentation for details TABLE 3 1 Connection parameters Argument Required Description HOSTADDRESS Yes Payflow host name HOSTPORT Yes PARMLIST Yes TIMEOUT Yes PROXY ADDRESS No PROXYPORT No PROXYLOGON No PROXYPASSWORD No For live transactions use payflowpro verisign com For testing purposes use pilot payflowpro verisign com Use port 443 The PARMLIST is the list of parameters that specify the payment information for the transaction The quotation marks and end are required The following is an exampl
44. ar at the top left of the payment page The image has 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 Sets the border colour around the header of the payment page The border is two pixel perimeter around the header space which is 750 pixels wide by 90 pixels high Type String String Alpha upper case or lower case AU or en AU DE or de DE FR or fr FR GB or en GB IT or it IT JP or ja JP US or en US Alpha String String HTML hexadecimal colour code in ASCII Max Length 30 127 Website Payments Pro Developer s Guide 55 0 PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions TABLE 6 2 Set Express Checkout request parameters Continued Parameter Name HDRBACKCOLOR PAYFLOWCOLOR ACTION Description Sets the background colour for the header of the payment page Sets the background colour for the payment page Is S to indicate this 15 Set Express Checkout request Max Type Length String 6 HTML hexadecimal colour code in ASCII String 6 HTML hexadecimal colour code in ASCII Alpha 1 Set Express Checkout Response Parameters Set Express Checkout response parameters include the RESULT and RESPMSG described in Chapter 8 Responses to Transaction Requests as well as TOKEN parameter described in
45. are described in Chapter 8 Responses to Transaction Requests Submitting Sale Transactions The Sale transaction TRXTYPE S charges the specified amount against the account and marks the transaction for immediate fund transfer during the next settlement period PayPal submits each merchant s transactions for settlement on a daily basis Website Payments Pro Developer s Guide 29 30 Performing Direct Payment Credit Card Transactions Submitting Sale Transactions When to Use Sale Transaction A Sale transaction is best suited to businesses that provide immediate fulfilment for their products or services Electronic goods merchants for example who fulfil orders immediately can use Sale transactions If your business does not provide immediate fulfilment then credit card association rules recommend that you use the Authorisation and Delayed Capture model For details see Submitting Authorisation Delayed Capture Transactions on page 31 If you need to recharge a credit card and you are not storing the credit card information in your local database you can perform a new reference transaction based on a Sale transaction For details see Recharging to the Same Credit Card Reference Transactions on page 37 Additional Parameters for Sale Transactions To perform a Sale transaction you are required to pass the following parameters ACCT AMT EXPDATE Typical Sale Transaction Parameter String The following is a typ
46. atures described in this document will be announced or made available to anyone in the future Preface Chapter Chapter Chapter Contents 7 Intended Audience s s sm s a 2222 lll ann 7 SCOPE op ace a a n hae Xx AR REGN a Pe E Xx e Red ee Mew m ut 7 Organisation of This Document 7 Where to Go for More 8 How to Contact Customer 8 1 Website Payments Pro Overview 9 How Website Payments 5 9 Supported Transactions gua a tn paa lel 10 Supported 5 10 Direct Payment Overview 11 PayPal Express Checkout 11 Additional 5 12 Business Rules 14 2 03 220246 L a adr sere Sa Weber woe nove fe 12 About the PayPal SDK ta aoa ers 12 2 Installing and Configuring the Payflow SDK 13 Supported 13 Preparing the Payflow Client Application 14 3 Creating a Simple Transaction Request 24 15 Transaction 5 15 Request 5 15 Data Modes for
47. ckout Details request parameter string TRXTYPE S amp VENDOR SuperMerchant amp USER SuperMerchant amp PWD SuperUserPassword amp TE NDER P amp PARTNER PayPalUK amp ACTION G amp TOKEN EC 17C76533PL706494p EXAMPLE 6 5 Get Express Checkout Details response RESULT 0 amp RESPMSG Approved amp AVSADDR Y amp TOKEN EC 17C76533PL706494P amp PAYERID FHY4JXY7CV9PG amp EMAIL buyer name aol com amp PAYERSTATU S verified amp CUSTOM TRVV14459 amp FIRSTNAME Chris amp LASTNAME A exander amp BUSINESS Mon roe Creek Regional Interiors amp SHIPTOSTREET 5262 Green Street 8 amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOZIP 95148 amp SHIPTOCOUNTRY US Redirecting the Customer to Your Website Example PayPal redirects the customer back to your website at the location you specified in the RETURNURL parameter to Get Express Checkout request PayPal appends the PAY ERID name value pair to the URL string as shown below http RETURNURL PayerID PAYERID You need to pass the PAY ERID in the Do Express Checkout Payment request described next Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing e PayPal Express Checkout Transaction Parameter Descriptions Do Express Checkout Payment ACTION D The Do Express Checkout Payment request performs the actual money transfer of the Sale transaction In addition to the parameters required by all transaction types described in Chapter 3 Creating a Simple Transacti
48. ctions Contact PayPal Customer Service to set your account s VERBOSITY setting to LOW or MEDIUM for all transaction requests Setting the Verbosity Level on a Per Transaction Basis To specify a setting for Verbosity that differs from your account s current setting include the VERBOSITY lt value gt name value pair in the transaction request where value is LOW or MEDIUM Website Payments Pro Developer s Guide 85 Verbosity Viewing Processor Specific Transaction Results Changing the Verbosity Setting 86 Website Payments Pro Developer s Guide ISO Country Codes The following International Standards Organisation ISO country codes are used when filling the order fields BILLTOCOUNTRY and POSTTOCOUNTRY TABLE B 1 Country codes Country Code ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGUILLA AI ANTIGUA AND AG BARBUDA ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD BARBADOS BB BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM Website Payments Pro Developer s Guide ae ISO Country Codes 88 TABLE B 1 Country codes Country BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BRAZIL BRITISH VIRGIN ISLANDS BRUNEI BULGARIA BURKINA FASO CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS CHILE CHINA COLOMBIA COOK ISLANDS COSTA RICA COTE D IVOIRE CROATIA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA
49. depending on the payment network Visa calls it CVV2 while MasterCard calls it CVC2 To ensure that your customers see a consistent name PayPal recommends use of the term card security code on all end user materials You must provide a CVV2 value as a transaction parameter for those credit cards that use card security code validation The value is required for Visa MasterCard Switch and Solo cards IMPORTANT 7o comply with credit card association regulations you must not store the CVV2 value 40 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions reel Card Security Code Validation American Express Card Security Code Enhancements In a card not present environment American Express recommends that you include the following information in your authorisation message e Card member billing name e Postal information SHIPTO parameters such as Address Name Postage method e Customer information such as Email address IP address Host name Browser type e Order information such as product SKU On most cards the card security code is printed on the back of the card usually in the signature field All or part of the card number appears before the card security code 567 in the example For details on PayPal processor card security code responses see Security Code Results on page 72 Wed Website Payments Pro Developer s Guide 41 En Perfo
50. difying the recurring profile Error in cancelling the recurring profile Error in forcing the recurring profile Error in reactivating the recurring profile OLTP Transaction failed Invalid recurring profile ID Insufficient funds available in account Exceeds per transaction limit General error See RESPMSG Transaction type not supported by host Time out value too small Processor not available Error reading response from host Timeout waiting for processor response Try your transaction again Credit error Make sure you have not already credited this transaction or that this transaction ID is for creditable transaction For example you cannot credit an authorisation Host not available Duplicate suppression time out 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 number greater than zero if the transaction has been settled If the transaction has already settled your only recourse is reversal credit payment or submit payment for credit Time out waiting for host response Referenced auth against order Error Capture error Either an attempt to capture a transaction that is not an authorisation transaction type or an attempt to capture an authorisation transaction that has already been captured Failed AVS check Address and ZIP code do not ma
51. e TRXTYPE S amp TENDER C amp PARTNER PayPalUK amp VENDOR SuperMercha nt amp USER SuperMerchant amp PWD SuperUserPassword amp AMT 123 00 The content of the PARMLIST varies by the type of transaction being processed For example Void transaction requires different set of parameters than a Sale at the beginning Time out period for the transaction The minimum recommended time out value is 30 seconds The client begins tracking from the time that it sends the transaction request to the server Proxy server address Use the PROXY parameters for servers behind a firewall Your network administrator can provide the values Proxy server port Proxy server logon ID Proxy server logon password PARMLIST Syntax Guidelines Follow these guidelines when creating the PARMLIST 2 Spaces are allowed in values Enclose PARMLIST in quotation marks Do not place quotation marks within the body of the PARMLIST 2 Separate all name value pairs in the PARMLIST using an ampersand amp 2 Payflow SDKSet the VERBOSITY transaction parameter to MEDIUM default is LOW if you want the response to return more detailed information For details see Appendix A Verbosity Viewing Processor Specific Transaction Results Website Payments Pro Developer s Guide Creating a Simple Transaction Request I Transaction Request Using Special Characters in Values Because the ampersand amp and equal sign characters
52. e Payments Pro Developer 5 Guide describes Website Payments Pro and how to integrate it into your website using the Payflow SDK The product offers two website payment solutions PayPal Direct Payment and PayPal Express Checkout Intended Audience This guide is written for merchants who have signed up through PayPal Manager to use PayPal as their processor and Website Payments Pro as their solution for handling payment transactions on their website This guide assumes that its readers e Are experienced web or application developers e Have a background in payments services Scope This guide describes the Payflow SDK programming interfaces needed to integrate Website Payments Pro into your website along with guidelines and best practices for presenting these payment offerings Organisation of This Document The guide is organised into the following chapters and appendices e Chapter 1 Website Payments Pro Overview provides a brief overview of the product e Chapter 2 Installing and Configuring the Payflow SDK describes where to get the Payflow SDK and how to install it e Chapter 3 Creating a Simple Transaction Request identifies a common set of transaction data required in all transactions and provides syntax guidelines on how to format it so that it can be understood by the Payflow server e Chapter 4 Performing Direct Payment Credit Card Transactions describes how you can implement Direct Payment
53. e final review page on your website where the customer confirms the order and payment Likewise CANCELURL should be the URL of the original page on your website where the customer initially chose to use PayPal EXAMPLE 6 2 Set Express Checkout response RESULT 0 amp RESPMSG Approved amp TOKEN EC 17C76533PL706494P You use the TOKEN value in the response to refer to this particular transaction in the following requests to PayPal as shown in Figure 6 1 on page 48 e Inthe HTTP request to redirect the customer s browser to the PayPal website described in Redirecting the Customer to PayPal Example on page 51 e Inthe Get Express Checkout Details request to obtain the customer s billing information described in Redirecting the Customer to PayPal Example on page 51 e Inthe Do Express Checkout Payment request to carry out the transaction described in Do Express Checkout Payment ACTION D on page 53 Redirecting the Customer to PayPal Example After your buyer clicks the PayPal button and you submit the Set Express Checkout request you will want to automatically direct your customer 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 where TOKEN is the value returned in the Set Express Checkout response PayPal recommends that you use the HTTPS response 302 Object Moved with your URL as the value of the Location header in the HTTPS re
54. e transaction setting CAPTURECOMPLETE to Y EXAMPLE 4 11 Delayed Capture with CAPTURECOMPLETE Y TRXTYPE D amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp CAPTURECOMPLETE Y amp ORIGID EFHPOD426A51 amp AMT 34 00 RESULT 0 amp PNREF VXYZ0123456 9 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CORRELATIONI D 2dc60e253493e Delayed Capture Transaction Capturing Transactions for Higher Amounts You can perform Delayed Capture transaction for an amount higher than the original Authorisation amount however you are charged for an extra transaction In addition the cardholder s open to buy is reduced by the sum of the original Authorisation only amount and the final Delayed Capture amount Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions el Submitting Credit Transactions Delayed Capture Transaction Error Handling and Retransmittal If an error occurs while processing Delayed Capture transaction it is safe to retry the capture with values that allow the server to successfully process it Conversely if a capture for previous Authorisation succeeds subsequent attempts to capture it again will return an error Submitting Credit Transactions The Credit transaction TRXTYPE C refunds the specified amount to the cardholder Required Credit Transaction Parameters Credit transactions are permitted only against existing
55. edit card Note Direct Payment is not a standalone feature You must use Direct Payment together with PayPal Express Checkout See Chapter 7 PayPal Button Placement and Page Designs for guidelines on how to display the PayPal mark logo with credit card logos With the exception of a few optional PayPal Express Checkout transaction parameters not covered here this chapter describes all required Website Payments Pro Payflow Edition request parameters Differences exist in PayPal Express Checkout transactions however and these are explained in Chapter 6 PayPal Express Checkout Transaction Processing In This Chapter e How Direct Payment Works on page 22 e About Direct Payment Credit Card Processing on page 22 e Parameters Used in Transactions on page 23 e Additional Parameters by Transaction Type on page 29 e Submitting Sale Transactions on page 29 e Submitting Authorisation Delayed Capture Transactions on page 31 e Submitting Credit Transactions on page 35 e Submitting Void Transactions on page 36 e Recharging to the Same Credit Card Reference Transactions on page 37 e Using Address Verification Service on page 39 e Card Security Code Validation on page 40 Website Payments Pro Developer s Guide 21 22 Performing Direct Payment Credit Card Transactions How Direct Payment Works How Direct Payment Works Figure 3 1 shows the general flow of customer checkout with Direct Payment Yo
56. ers Important Note Result code 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 authorised but requires you to review and manually accept the transaction before it will be allowed to settle Result code 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 see the Fraud Protection Services documentation for your payments solution It is available on the PayPal Manager Documentation page 127 Fraud Protection Services Filter Not processed by filters 128 Fraud Protection Services Filter Declined by merchant after being flagged for review by filters 131 Version 1 Website Payments Pro SDK client no longer supported Upgrade to the most recent version of the Website Payments Pro client 132 Card has not been submitted for update Website Payments Pro Developer s Guide 77 78 Responses to Transaction Requests RESULT Codes and RESPMSG Values TABLE 8 5 Payflow transaction RESULT values and RESPMSG text Continued RESULT 133 150 151 200 201 402 403 404 600 601 1000 1001 1002 1003 1004 1011 1012 1013 1014 1016 1017 1021 1022 1023 RESPMSG and Explanation Data mismatch in HTTP retry request
57. ervat ion amp ORIGID EFHP0D426838 EXAMPLE 4 7 Delayed Capture response RESULT 0 amp PNREF EFHP0D42687C amp RESPMSG Approved amp PPREF 1F987159809825103 amp CORREL ATIONID b5689409e279f amp FEEAMT 0 56 amp PAYMENTTYPE instant amp PENDINGREASON complet ed Delayed Capture Transaction Capturing Transactions for Lower Amounts You can perform a Delayed Capture transaction for an amount lower than the original Authorisation amount useful for example when you make a partial delivery To perform a partial capture programmatically using the PayPal SDK set CAPTURECOMPLETE to N in the Delayed Capture transaction request Setting CAPTURECOMPLETE to Y voids any remaining amount of the original authorised transaction You can also perform Authorisations and Delayed Captures through PayPal Manager For details see PayPal Manager Online Help Example Partial Capture Transaction In this example you authorise an amount of 100 for a consignment and charge 66 for the first partial delivery using a Delayed Capture transaction You charge the 34 for the final part of the delivery using a second Delayed Capture transaction to draw credit card and postal address information from the initial Authorisation transaction Website Payments Pro Developer s Guide 33 34 Performing Direct Payment Credit Card Transactions Submitting Authorisation Delayed Capture Transactions Step 1 Submit the Initial transaction Authorisation in this example This
58. eturned by Set Express String 20 Checkout response SHIPTOSTREET Postal Address String 30 NoTE If you include a postal address and provide a value for the AddressOverride ADDROVERRIDE parameter PayPal returns this same address in the Get Express Checkout Details response SHIPTOSTREET2 Extended postal address Example Bldg String 30 6 Flat 3 SHIPTOBUSINESS Customer s business name String 127 Website Payments Pro Developer s Guide 57 0 PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions TABLE 6 5 Get Express Checkout Details response parameters Continued Max Parameter Name Description Type Length SHIPTOCOUNTRYCODE Customer s country of residence in the String 2 form of ISO standard 3166 two character country codes NOTE Currently US is the only country code supported PAYERID Unique PayPal customer account String 13 identification number PAYERSTATUS Status of customer Values are Alpha 10 verified unverified CUSTOM Free form field for your own use as set by Alpha 256 you in the Set Express Checkout request numeric PHONENUM Account holder s telephone number See String 20 Obtaining the Customer s Telephone Number During PayPal Checkout on page 58 The field mask is Xxx xxx xxxx US numbers XXXXXXXXXXX international numbers Obtaining the Customer s Telephone Number During PayPal Checkout You can request the buyer s phone number from wi
59. example uses an Authorisation transaction for the full amount of purchase of 100 EXAMPLE 4 8 Authorisation for the full amount of the purchase TRXTYPE A amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 100 00 amp INVNU M 123456789 amp FIRSTNAME John amp LASTNAME Jones amp STREET 5199 MAPLE amp ZIP 94588 Note the value of the PNREF in the response EXAMPLE 4 9 Response to the Authorisation RESULT 0 amp PNREF EFHP0D426A51 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATCH X amp PPREF 6FS950632E172331R amp CORRELATIONID 3c1a7c1c411a Step 2 Capture the authorised funds for a partial delivery of 66 When you deliver the first 66 worth of product you use a Delayed Capture transaction to collect the 66 Set ORIGID to the value of PNREF in the original Authorisation and set CAPTURECOMPLETE to N EXAMPLE 4 10 Delayed Capture with CAPTURECOMPLETE N TRXTYPE D amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp CAPTURECOMPLETE N amp ORIGID EFHPO0D426A51 amp AMT 66 00 RESULT 0 amp PNREF VXYZ012 34568 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZI P N amp CORRELATIONI D 2dc60e253492e Step 3 Capture the 34 balance for the rest of the consignment Once you have sent the remainder of the product you can collect the remaining 34 in second Delayed Captur
60. g Direct Payment Credit Card Transactions Submitting Void Transactions Submitting Void Transactions The Void transaction TRXTYPE V prevents a transaction from being settled but does not release the Authorisation hold on funds on the cardholder s account When to Use a Void Transaction Follow these guidelines e You can only void Authorisation transactions e You can only use a Void transaction on a transaction that has not yet settled To refund a customer s money for a settled transaction you must submit a Credit transaction Required Void Transaction Parameters To submit a Void transaction you must pass the following parameter ORIGID Set ORIGID to the PNREF Transaction ID in PayPal Manager reports value returned for the original transaction For details on PNREF see Chapter 8 Responses to Transaction Requests Fields Copied from the Original Transaction into the Void Transaction The following fields are copied from the original transaction into the Void transaction if they exist in the original transaction If you provide new value for any of these parameters when submitting the Void transaction then the new value is used Exceptions are ACCT and EXPDATE These parameters retain their original values ACCT AMT CITY COMMENTI CLIENTIP COMMENT2 COUNTRY CUSTCODE EMAIL EXPDATE FIRSTNAME FREIGHTAMT INVNUM LASTNAME NOTE PHONENUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOS
61. horisation and Delayed Capture depending on your business model Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions Parameters Used in Transactions For an Authorisation PayPal sends the transaction information to the cardholder s issuing bank The issuing bank checks whether the card is valid evaluates whether sufficient credit exists checks values such as Address Verification Service and card security codes and returns a response Approval Decline Referral or others For details on Address Verification Service and card security codes see e Using Address Verification Service on page 39 e Card Security Code Validation on page 40 You receive the response shortly after you submit the transaction to PayPal If the Authorisation is approved the bank temporarily reserves credit for the amount of the transaction to prepare to capture fulfil the transaction The hold on funds typically lasts for about a week Capturing a transaction also known as settling a transaction actually transfers the funds to PayPal At least once a day the Payflow server gathers all transactions that are flagged to be settled and sends them in a batch file to PayPal PayPal charges the issuing bank and transfers the funds to your PayPal account It typically takes a few days before the money is actually available in your PayPal account Considerations Regarding Your Website Integration In the design of y
62. ical PARMLIST string passed in a Sale transaction EXAMPLE 4 1 Typical Sale transaction parameter string TRXTYPE S amp TENDER C amp USER SuperMerchant amp PWD SuperUserPassword amp PARTNER PayPal UK amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT1 Reservation amp FIRSTN AME John amp LASTNAME Jones amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CLIENTIP 0 0 0 0 Note that besides the required parameters that you pass in Sale transaction this string includes other typical parameters PayPal recommends that you include the account holder s FIRSTNAME and LASTNAME PayPal also recommends including CLIENTIP to help detect possible fraud The COMMENTI field helps to track transaction information The customer s postal address STREET and ZIP postcode should be passed to use the Address Verification Service AVS CVV2 is needed for card security code validation For details on AVS and card security code see the following sections e Using Address Verification Service on page 39 e Card Security Code Validation on page 40 The following is a typical set of Response parameters See Chapter 8 Responses to Transaction Requests for details on response parameters EXAMPLE 4 2 Typical response parameters RESULT O amp PNREF EFIPOD391C30 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATCH X amp PPREF 7XX11903GL026951F amp CORRELATIONID 3a5df00
63. ification number This value is returned in the URL when the customer is redirected to your website Website Payments Pro Developer s Guide 59 0 PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions TABLE 6 6 Do Express Checkout Payment request parameters Continued Parameter Name TAXAMT Description Required Type Sum of tax for all items in this order No Decimal NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies CURRENCY is described in Table 4 1 Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be period Do not use comma separators Use 1199 95 not 1 199 95 Max Length 6 Do Express Checkout Payment Response Parameters The Do Express Checkout Payment response parameters include e RESULT RESPMSG PNREF and PPREF described in Chapter 8 Responses to Transaction Requests e The parameters described in Table 6 7 TABLE 6 7 Do Express Checkout Payment response parameters Parameter Name TOKEN FEEAMT PAYMENTTYPE Description Type The time stamped token value that was returned String in the Set Express Checkout response PayPal fee amount charged for the transaction Decimal NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies CURRENCY
64. is described in Table 4 1 Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be a period Do not use comma separators Use 1199 95 not 1 199 95 Returns instant if the payment is instant or Alpha eCheque if the payment is delayed Max Length 20 60 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing e PayPal Express Checkout Transaction Parameter Descriptions TABLE 6 7 Do Express Checkout Payment response parameters Continued Max Parameter Name Description Type Length TAXAMT Sum of tax for all items in this order Decimal 6 NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies CURRENCY is described in Table 4 1 Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be period Do not use comma separators Use 1199 95 not 1 199 95 PENDINGREASON The reason the payment is pending Values are String none No pending reason address The payment is pending because your customer did not include confirmed postal address and your Payment Receiving Preferences is set such that you want to manually accept or refuse each of these payments To change your preference go to the Preferences section of your Profile echeque The payment is pending because it was made by an eCheque that has not yet cleared i
65. loper s Guide
66. mp Billing Info Website Payments Pro Developer s Guide Website Payments Pro Overview Supported Transactions After selecting products to purchase your customer chooses whether they want to pay using PayPal or pay using credit cards directly on your website If your customer pays using credit cards on your website PayPal processes them in the background If your customer chooses to use PayPal your customer is transferred to PayPal to log in and select postal address and payment method and is returned to your website to complete their purchase Once the buyer completes their order you receive your payment Supported Transactions Website Payments Pro supports the following transaction types Sale Authorisation Void Delayed Capture Credit Chapter 4 Performing Direct Payment Credit Card Transactions describes the transaction types in detail and identifies the minimum parameters that you must send for each Supported Currencies Website Payments Pro supports the following currencies e USD US dollar e EUR Euro e GBP UK pound e CAD Canadian dollar e JPY Japanese Yen e AUD Australian dollar Unlike other processors that require you to set up a separate account for each currency PayPal allows you to run transactions using any of the six currencies with a single account Website Payments Pro Developer s Guide Website Payments Pro Overview Ei Direct Payment Overview Direct Payment O
67. mple V53A17230645 e For live servers the first four characters were alpha characters letters for example VPNE12564395 However this is not always the case and as a rule you should not place any meaning on the contents of a PNREF RESULT Codes and RESPMSG Values RESULT is the first value returned in the server response string The value of the RESULT parameter indicates the overall status of the transaction attempt e A value of 0 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 value greater than zero indicates a decline or error The response message RESPMSG provides a brief description for decline or error results RESULT Values for Transaction Declines or Errors For non zero Results 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 TABLE 8 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 following 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 Hel
68. ns Parameters Used in Transactions Transaction parameters Continued Parameter ZIP BUTTONSOURCE CARDISSUE CARDSTART CLIENTIP COMMENTI COMMENT2 CAPTURECOMPLETE Description Account holder s five to nine digit bill to ZIP code or other country specific bill to postcode Do not use spaces dashes or non numeric characters ZIP is verified by Address Verification System and the International Address Verification System described on page 39 Identification code for use by third party applications to identify transactions Issue number of Switch or Solo card NoTE For Switch or Solo transaction to be approved either CARDISSUE or CARDSTART must be present Date that Switch or Solo card was issued in mmyy format For example 0308 represents March 2008 NoTE For a Switch or Solo transaction to be approved either CARDISSUE or CARDSTART must be present 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 This value is in dotted quad format XXX XXX XXX XXX Merchant defined value for reporting and auditing purposes See Using Address Verification Service on page 39 Merchant defined value for reporting and auditing purposes Indicates if this Delayed Capture transaction is the last capture you intend to make The values are e Y default e N Norte
69. nt holder s first name Account holder s last name 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 Description of items the customer is purchasing ID of the original Direct Payment transaction that is being referenced This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports Limitations This value is case sensitive Type of transaction occurrence The values are F First occurrence S Subsequent occurrence default SHIP TO Address Information Next five table entries SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY SHIPTOZIP Post to postal address Name of post to city Name of post to county or province Post to country code See Appendix B ISO Country Codes US post to ZIP code or other country specific postcode Required No No but recom mended No but recom mended No a Yes Type String Alpha Alpha Alpha numeric Alpha numeric Alpha numeric Alpha String String String Alpha String Max Length 64 25 25 2048 127 12 30 40 10 20 28 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions d Additional Parameters by Transaction Type TABLE 4 1 Transaction parameters Contin
70. ntl The payment is pending because you hold a non US account and do not have a withdrawal mechanism You must manually accept or refuse this payment from your Account Overview 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 refuse this payment verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment other The payment is pending for a reason other than those listed above For more information contact PayPal customer service completed The payment has been completed and the funds have been added successfully to your account balance Website Payments Pro Developer s Guide 61 0 PayPal Express Checkout Transaction Processing PayPal Express Checkout Transaction Parameter Descriptions Pending Payments If the Do Express Checkout Payment PENDINGREASON response is a value other than none or Completed the payment is pending Typically the customer has paid with an eCheque In such a case funds are not guaranteed and you should not send or deliver items or services until the payment has successfully completed To find out the status of a pending payment sign up for PayPal s instant payment notification service IPN You can also check the status using PayPal Manager See PayPal Manager Online Help for de
71. o gt Processor Info in PayPal Manager Credit Card Numbers Used for Testing Use the following credit card numbers for testing Any other card number produces a general failure TABLE 5 1 Test credit card numbers American Express 3782822463 10005 American Express 371449635398431 Amex Corporate 37873449367 1000 Australian BankCard 5610591081018250 Diners Club 30569309025904 Diners Club 38520000023237 Discover 6011111111111117 Discover 6011000990139424 JCB 3530111333300000 JCB 3566002020360505 MasterCard 5555555555554444 Website Payments Pro Developer s Guide 43 Testing Credit Card Transactions Testing Result Code Responses TABLE 5 1 Test credit card numbers Continued MasterCard Visa Visa Visa 5105105105105100 4111111111111111 4012888888881881 4222222222222 NOTE Even though this number has a different character count than the other test numbers it is the correct and functional number Testing Result Code Responses You can use the amount of the transaction to generate a particular result code Table 5 2 lists the general guidelines for specifying amounts TABLE 5 2 Result codes resulting from amount submitted Amount Result RESPMSG 0 10000 0 Approved 10001 or greater Certain amounts in this range return specific PayPal result codes If the amount is in this range but does not correspond to a PayPal result code supported by this testing mechanism result 1000 is returned
72. on Request Do Express Checkout Payment request requires that you pass data for these parameters ACTION TOKEN PAYERID AMT EXAMPLE 6 6 Do Express Checkout Payment request parameter string TRXTYPE S amp VENDOR SuperMerchant amp USER SuperMerchant amp PWD SuperUserPassword amp TE NDER P amp PARTNER PayPalUK amp ACTION D amp TOKEN EC 17C76533PL706494P amp PAYERID FHYAUXY7CV9PG amp AMT 35 00 EXAMPLE 6 7 Do Express Checkout Payment response RESULT 0 amp PNREF EFHPOCDBF5C7 amp RESPMSG Approved amp AVSADDR Y amp TOKEN EC 17C76533PL706494P amp PAYERID FHY4JXY7CV9PG amp PPREF 2P599077L3553652G amp PAYMENTTYPE instant The response returns 12 character PNREF Payflow Manager Transaction ID that is used by PayPal to identify this transaction in PayPal Manager reports The PPREF value maximum of 17 characters is used by PayPal only to identify this transaction For details on response parameters see Chapter 8 Responses to Transaction Requests PayPal Express Checkout Transaction Parameter Descriptions Sale and Authorisation Transaction Parameters Set Express Checkout Request Parameters The Set Express Checkout request parameters include the following e The parameters required by all transaction types described in Chapter 3 Creating Simple Transaction Request e The following required parameters described in PayPal Express Checkout Sale Transaction Example on page 50 ACTION AMT RETURNURL CANCELURL
73. or conditions returned by the PayPal processor vary in detail level and in format The VERBOSITY parameter enables you to control the kind and level of information you want returned By default VERBOSITY is set to LOW A LOW setting causes the server to normalise the transaction result values Normalising the values limits them to standardised set of values and simplifies the process of integrating Website Payments Pro By setting VERBOSITY to MEDIUM you can view PayPal s raw response values This setting is more verbose than the LOW setting in that it returns more detailed processor specific information Supported Verbosity Settings PayPal supports the following VERBOSITY settings e LOW This is the default setting for Website Payments Pro accounts The following values are returned RESULT PNREF RESPMSG AUTHCODE AVSADDR AVSZIP CVV2MATCH IAVS CARDSECURE e MEDIUM All the values returned for a LOW setting plus the following values Note For information on interpreting the responses returned by the processor for the MEDIUM VERBOSITY setting contact your processor directly TABLE A 1 Verbosity settings Field Name Type Length Description HOSTCODE char 7 Response code returned by the PayPal processor This value is not normalised RESPTEXT char 17 Text corresponding to the response code returned by the PayPal processor This text is not normalised PROCAVS char 1 AVS response from the PayPal processor PROCCV
74. ory included with the SDK that you downloaded For specific information on setting the certificate path see the readme txt file and example applications in the SDK Step 5 Read the readme txt file The readme txt file includes integration information and samples that illustrate how to use the client in your development environment 14 Website Payments Pro Developer s Guide Creating Simple Transaction Request This chapter describes how to create simple Sale transaction request The chapter focuses on the common set of parameters required in all transactions and how you set up these parameters using name value pair strings Additional parameters are required depending on the transaction type You can also provide many optional parameters depending on the results you want returned For example you can set the VERBOSITY parameter to return PayPal processor specific details rather than normalised information if you are looking for this kind of information In This Chapter e Transaction Request on page 15 e Sale Transaction Example on page 18 e How to Format a Transaction on page 19 Transaction Request Request Contents A transaction request includes the following e Connection parameters e Parameters required by all transactions This list includes user information parameters e Additional parameters required by the type of transaction Data Modes for Sending You can send parameter data in the tr
75. our website integration you should consider whether you want to store information in your local database or use PayPal Manager reports to manage the data You may want to store postal information in your system or you may prefer to send the information to PayPal with the transaction and report on it later Note PayPal recommends that you do not store credit card numbers If you must store numbers encrypt and store them behind properly configured firewalls You should also consider whether and how to use the merchant defined fields COMMENTI and COMMENT to help tie PayPal reports to your orders customers or to report on other information about the transaction If you want to integrate with other systems such as order fulfilment customer service and so on you may want to connect these systems directly to Website Payments Pro for capturing funds issuing refunds credits and so on Alternatively you may prefer to perform these steps manually using PayPal Manager Either way PayPal recommends that you monitor transaction activity using PayPal Manager Parameters Used in Transactions PayPal accepts the parameters listed in Table 4 1 The table indicates whether the parameters are required or optional Website Payments Pro Developer s Guide 23 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions Note Unless otherwise noted the parameters in Table 4 1 can be used in Direct Payment and PayPal Expre
76. p 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 URL from pilot payflowpro verisign com to payflowpro verisign com 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 authorisation only transaction Website Payments Pro Developer s Guide Responses to Transaction Requests 8 RESULT Codes and RESPMSG Values TABLE 8 5 Payflow transaction RESULT values and RESPMSG text Continued RESULT RESPMSG and Explanation 4 Invalid amount format Use the format Do not include currency symbols or commas 5 Invalid merchant information Processor does not recognise your merchant account information Contact your bank account acquirer to resolve this problem 6 Invalid or unsupported currency code 7 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 expiry 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
77. proved Authorisation transaction be sure to perform a Delayed Capture transaction not a Reference transaction e Void e Delayed Capture e Credit Note PayPal Express Checkout does not support reference transactions for Authorisations or Sales Reference transactions are only supported for Voids Delayed Captures and Credits For details on PayPal Express Checkout see Chapter 6 PayPal Express Checkout Transaction Processing Fields Copied from Reference Transactions The following fields are copied from the reference transaction into the new Sale or Authorisation transaction 1f they exist in the original transaction If you provide a value for any of these parameters when submitting the new transaction then the new value is used ACCTTYPE STREET ACCT CITY EXPDATE STATE FIRSTNAME ZIP LASTNAME COUNTRY Example Reference Transaction In this example you authorise an amount of 100 for a consignment and charge 66 for the first partial delivery using a normal Delayed Capture transaction You charge the 34 for the final part of the delivery using a reference transaction to draw credit card and postal address information from the initial Authorisation transaction Step 1 Submit the Initial transaction Authorisation in this example You use an Authorisation transaction for the full amount of the purchase of 100 EXAMPLE 4 13 Authorisation for the full amount of the purchase TRXTYPE A amp TENDER C amp PWD SuperUserPass
78. rameter 62 NOTIFYURL parameter 28 testing 43 ORDERDESC parameter 28 ORIGID parameter 28 overview PayPal Express Checkout 48 p PAGESTYLE parameter 55 Partner Manager overview 8 PARTNER parameter 17 PAYERID in RETURNURL 52 PAYERID parameter 58 59 PAYERSTATUS parameter 58 PAYFLOWCOLOR parameter 56 PAYMENTTYPE parameter 60 63 PayPal Express Checkout ACTION values 49 Do Express Checkout Payment ACTION D example 53 Do Express Checkout Payment request parameters 59 Do Express Checkout Payment response parameters 60 Get Express Checkout Details ACTION G example 52 Get Express Checkout Details request parameters 57 Get Express Checkout Details response parameters 57 Set Express Checkout example 50 Set Express Checkout request parameters 53 Set Express Checkout response parameters 56 PayPal Express Checkout Sale and Authorisation transactions 49 PayPal Express Checkout Sale parameters 51 PayPal Express Checkout transaction parameter descriptions 53 PENDINGREASON parameter 61 PHONENUM parameter 58 PNREF format of value 73 PNREF value 73 processor raw response values 29 PWD parameter 18 R RECURRINGTYPE parameter 28 redirecting customers to PayPal 51 reporting and auditing 25 REQCONFIRMSHIPPING parameter 54 RESPMSG value 74 response values processor 29 responses credit card transaction 69 RESULT value 74 RESULT values communication errors 80 RETURNURL parameter
79. rming Direct Payment Credit Card Transactions Card Security Code Validation Example CVV2 Request Parameter String This example request parameter string includes the CV V2 parameter EXAMPLE 4 19 CVV2 request parameter string TRXTYPE A amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 amp CVV 2 567 Example CVV2 Response In this example result the card security code value matches the value in the bank s records EXAMPLE 4 20 CVV2 response RESULT 0 amp PNREF VXW412345678 amp RESPMSG APPROVED amp CVV2MATCH Y amp CORRELATIONID 2dc 60 2534971 42 Website Payments Pro Developer s Guide Testing Credit Card Transactions To test your application direct all transactions to pilot payflowpro verisign com Transactions directed to this URL are processed through PayPal s simulated payment network enabling you to test the configuration and operation of your application or shopfront no money changes hands You must activate your account and configure your application for live transactions before accepting real orders Testing Guidelines a Ip Ip While testing use only the credit card numbers listed in this chapter Other numbers produce an error Expiry Date must be a valid date in the future use the mmyy format To view the credit card processor that you have selected for testing see Account Inf
80. rns the same response as 123 Elm Street The International Address Verification Service response indicates whether the AVS response is international Y USA N or cannot be determined X SDK version 3 06 or later is required Example AVS Request Parameter String This example request includes the AVS request parameters STREET and ZIP EXAMPLE 4 17 Request string with AVS request parameters TRXTYPE A amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp ACCT 5555555555554444 amp EXPDATE 03 08 amp AMT 123 00 amp STRE ET 5199 Maple amp ZIP 98765 Example AVS Response In this example the address value matches the value in the bank s records but the postcode does not The IAVS response is X EXAMPLE 4 18 AVS response parameters RESULT 0 amp PNREF EFHP0D426A56 amp RESPMSG APPROVED amp AVSADDR Y amp AVSZIP N amp IAVS X amp CORR ELATIONID 2dc60e253496a For details on Address Verification responses see Address Verification Responses from PayPal on page 71 Card Security Code Validation The card security code is a three or four digit number not part of the credit card number that is printed on the credit card Because the card security code appears only on the card and not on receipts or statements the card security code provides some assurance that the physical card is in the possession of the buyer Norte This fraud prevention tool has various names
81. rted X U Unavailable X No Response X All other X PNREF Value The PNREF is a unique transaction identification number issued by the Payflow server 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 I and voids TRXTYPE V e The PNREF value is used as the ORIGID value original transaction ID value in reference transactions for authorisation TRXTYPE A and Sale TRXTYPE S Nore The PNREF is also referred to as the Transaction ID in Payflow Link documentation PNREF Format The PNREF is a 12 character string of printable characters for example e EFHPOD42687C e ACRAF23DB3C4 Note Printable characters also include symbols other than letters and numbers such as the question mark A PNREF typically contains letters and numbers only Website Payments Pro Developer s Guide 73 74 Responses to Transaction Requests RESULT Codes and RESPMSG Values The PNREF in a transaction response tells you that your transaction is connecting to PayPal Historically the contents of a PNREF indicated a test or a live transaction e For test servers the first and fourth characters were alpha characters letters and the second and third characters were numeric for exa
82. s Verification Service 39 ADDROVERRIDE parameter 55 AMT parameter 24 application testing 43 AVS see Address Verification Service B BILL TO address parameters 24 business rules 12 BUTTONSOURCE parameter 25 C CANCELURL parameter 54 card security code 40 CARDISSUE parameter 25 CARDSTART parameter 25 CITY parameter 24 CLIENTIP parameter 25 30 COMMENT I parameter 25 COMMENT parameter 25 communications errors 80 COMPLETETYPE parameter 25 33 COUNTRY parameter 24 credit card association regulations 40 currency code format 24 currency codes 26 CURRENCY parameter 26 CUSTOM parameter 26 54 58 CUSTREF parameter 26 CVV2 parameter 26 30 D Do Express Checkout Payment request 50 53 Website Payments Pro Developer s Guide E EXPDATE parameter 26 F FEEAMT parameter 60 FIRSTNAME parameter 28 fraud detection 28 30 40 FREIGHTAMT parameter 26 G Get Express Checkout Details request 50 52 H HANDLINGAMT parameter 27 HDRBACKCOLOR parameter 56 HDRBORDERCOLOR parameter 55 HDRIMG parameter 55 HostAddress 16 Instant Payment Notification 28 International Standards Organisation ISO country codes 87 INVNUM parameter 27 ITEMAMT parameter 27 K knowledgbase URL 8 L LASTNAME parameter 28 length tags 17 LOCALECODE parameter 55 MAXAMT parameter 54 MEMO parameter 63 MERCHANTSESSIONID parameter 28 META REFRESH 51 95 N NAME Information parameters 28 NOSHIPPING parameter 55 NOTE pa
83. saction Parameters on page 63 Note PayPal Express Checkout supports reference transactions for Void Delayed Capture and Credit transactions PayPal Express Checkout Sale Transaction Example This section provides an example of a Sale transaction All required transaction parameters are described in Chapter 4 Performing Direct Payment Credit Card Transactions Set Express Checkout ACTION S The Set Express Checkout request passes the transaction details from your website to PayPal when a customer chooses to pay with PayPal 50 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing e PayPal Express Checkout Sale Transaction Example In addition to the parameter values required by all transaction types described in Chapter 3 Creating a Simple Transaction Request and the minimum required parameters for a Sale transaction described in Chapter 4 Performing Direct Payment Credit Card Transactions Set Express Checkout requires that you pass data for the following parameters ACTION AMT RETURNURL CANCELURL EXAMPLE 6 1 Set Express Checkout request parameter string for a Sale transaction TRXTYPE S amp ACTION S amp AMT 35 00 amp CANCELURL http www order page com amp PARTNER P ayPalUK amp PWD SuperUserPassword amp RETURNURL ht tp www confirmation_page com amp TE NDER P amp USER SuperMerchant amp VENDOR SuperMerchant It is strongly recommended that RETURNURL be the URL of th
84. sponse Alternatively you can generate a web page for your buyer that includes a META REFRESH tag in the header An example is shown below Remember to replace lt TOKEN gt with the token value that you received in the Set Express Checkout response Website Payments Pro Developer s Guide 51 52 PayPal Express Checkout Transaction Processing PayPal Express Checkout Sale Transaction Example EXAMPLE Generating a web page with META REFRESH tag lt html gt lt head gt 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 mobile phone do not support META refresh tags 2 a hrefz 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 customer s billing information such as the postal address and email address In addition to the parameters required by all transaction types described in Chapter 3 Creating Simple Transaction Request Get Express Checkout Details requires that you pass data for these parameters ACTION TOKEN EXAMPLE 6 4 Get Express Che
85. ss Checkout transactions See Chapter 6 PayPal Express Checkout Transaction Processing for additional optional PayPal Express Checkout parameters TABLE 4 1 Transaction parameters Parameter ACCT ACCTTYPE AMT Max Description Required Type Length Payer s credit card or account number It may Yes Numeric 19 not contain spaces non numeric characters or dashes For example ACCT 5555555555554444 Credit card type The following card types are No Alpha 10 supported 0 Visa 1 MasterCard 8 Other 9 Switch S Solo Total of this order Yes Decimal 10 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 No currency symbol Decimal separator must be a period Do not use comma separators Use 1199 95 not 1 199 95 BILL TO Address Next five table entries STREET CITY STATE COUNTRY Cardholder s bill to postal address number and No Alpha 100 street name numeric The STREET value is verified by Address Verification System described on page 39 Name of bill to city No String 40 Name of bill to county or province No String 40 Bill to country code See Appendix B ISO Alpha 2 Country Codes 24 Website Payments Pro Developer s Guide TABLE 4 1 Performing Direct Payment Credit Card Transactio
86. ss Verification Responses from PayPal in this chapter AVS postcode responses are for advice only This process does not affect the outcome of the authorisation See Using Address Verification Service on page 39 For details on PayPal specific responses also see Address Verification Responses from PayPal in this chapter AVS response from the processor when the merchant sends a VERBOSITY request parameter value of MEDIUM See Appendix A Verbosity Viewing Processor Specific Transaction Results for details response from the processor when the merchant sends a VERBOSITY request parameter value of MEDIUM See Appendix A Verbosity Viewing Processor Specific Transaction Results for details Type string Alphanumeric Alpha Y N X or no response Alpha Y N X or no response Char Char Length 17 Variable Website Payments Pro Developer s Guide Responses to Transaction Requests 8 Address Verification Responses from PayPal TABLE 8 1 Transaction response values Continued Field Description Type Length IAVS International AVS address responses are Alpha 1 for advice only This value does not affect N X or no the outcome of the transaction response Indicates whether AVS response is international Y US N or cannot be determined X Client version 3 06 or later is required See Using Address Verification Service on page 39 PAYMENTTYP
87. sting credit card numbers and Direct Payments For answers to specific questions about Payflow products search PayPal s Knowledge Base at the following URL http knowledge paypal com How to Contact Customer Service For problems with transaction processing or your connection to the server contact Customer Service at business support paypal co uk Website Payments Pro Developer s Guide Website Payments Pro Overview With Website Payments Pro you get the payment processing capabilities of merchant account and gateway plus much more It is an all in one payment solution that includes e Direct Payment Direct Payment enables you to accept credit card payments directly on your website PayPal remains invisible so you control the customer experience e PayPal Express Checkout PayPal Express Checkout allows PayPal account holders to check out fast with saved information and enables you to gain incremental sales from PayPal s growing base of users How Website Payments Pro Works Figure 1 1 High Level View 1s an example of a standard checkout process Website Payments Pro has the flexibility to work with your unique checkout process whether it is one page or has multiple steps FIGURE 1 1 High Level View Your Website Shopping Cart Postal Info Billing Info Order Review Order Complete Visa O MC O PayPal T Thank You CHECKOUT CONTINUE CONTINUE CONTINUE PayPal Website Shipping a
88. t directly from PayPal use PayPalUK The examples in this document use PARTNER PayPalUK Limitations This value is case sensitive Website Payments Pro Developer s Guide 17 18 Creating a Simple Transaction Request Sale Transaction Example TABLE 3 2 Required transaction parameters Continued PWD TENDER TRXTYPE Max Parameter Description Required Type Length The 6 to 32 character password that you defined while Yes Alphanumeric 32 registering for the account The examples in this document use PWD SuperUserPassword This value is case sensitive The tender type method of payment Values are Yes Alpha 1 e Credit card for Direct Payment transactions e P PayPal for PayPal Express Checkout transactions A single character indicating the type of transaction to Yes Alpha 1 perform Website Payments Pro supports the following values S Sale transaction Authorisation Credit D Delayed Capture V Void Sale Transaction Example In addition to the connection parameters and the required parameters in Table 3 2 each transaction type TRXTYPE has additional parameter requirements and can use a number of optional ones as well For example to perform a Direct Payment credit card Sale transaction you are required to pass the following parameters e ACCT The payer s credit card number e AMT The amount of the sale e EXPDATE The expiry date of the credit card Typical
89. tails Void Transaction Parameters In addition to the parameters required by all transaction types described in Chapter 3 Creating a Simple Transaction Request and the Void transaction parameters described in Chapter 4 Performing Direct Payment Credit Card Transactions the following NOTE parameter can be used in PayPal Express Checkout Void transactions TABLE 6 8 Void transaction optional request parameters Max Parameter Name Description Required Type Length NOTE An informal note about this settlement that No String 255 is displayed to the customer in an email and in the customer s transaction history Delayed Capture Transaction Parameters In addition to the parameters required by all transaction types described in Chapter 3 Creating a Simple Transaction Request and the Delayed Capture transaction parameters described in Chapter 4 Performing Direct Payment Credit Card Transactions the following NOTE parameter can be used in PayPal Express Checkout Delayed Capture transactions TABLE 6 9 Delayed Capture transaction optional request parameters Max Parameter Name Description Required Type Length NOTE An informal note about this settlement that No String 255 is displayed to the customer in an email and in the customer s transaction history 62 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing 6e PayPal Express Checkout Transaction Parameter Descriptions In
90. tails requests provide supporting data To distinguish between a Sale or Authorisation request you must pass an additional ACTION parameter with the respective value S or G Table 6 1 summarises the ACTION values and transaction types Website Payments Pro Developer s Guide 49 EE PayPal Express Checkout Transaction Processing PayPal Express Checkout Sale Transaction Example Note PayPal Express Checkout does not support reference transactions for Sales and Authorisations TABLE 6 1 Mapping PayPal Express Checkout requests to ACTION values Request TRXTYPE ACTION Set Express Checkout Identifies the transaction Is S for Set Express Checkout S Sale A Authorisation Get Express Checkout Details Identifies the transaction Is G for Get Express Checkout S Sale Details A Authorisation Do Express Checkout Payment Identifies the transaction Is D for Do Express Checkout S Sale Payment A Authorisation Void Delayed Capture and Credit Transactions You perform Void Delayed Capture and Credit transactions as described in Chapter 4 99 99 Performing Direct Payment Credit Card Transactions using the PayPal tender type Additional PayPal Express Checkout data parameters that you can use in these transaction types with PayPal Express Checkout are described in the following sections e Void Transaction Parameters on page 62 e Delayed Capture Transaction Parameters on page 62 e Credit Tran
91. tations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be period Do not use comma separators Use 1199 95 not 1 199 95 Line item name No String NOTE You can view line item information in the Transaction Details report in your PayPal merchant account Cost of line item No Decimal NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See the CURRENCY entry in this table for details Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be a period Do not use comma separators Use 1199 95 not 1 199 95 Line item quantity No String Line item tax amount No Decimal Limitations Any valid currency amount CURRENCY value must be set the same as for AMT Max Length 10 127 127 127 See description Any positive integer See description Website Payments Pro Developer s Guide 27 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4 1 Transaction parameters Continued Parameter MERCHANTSESSIONID Description Your customer Direct Payment session identification token PayPal records this session token as an additional means to detect possible fraud NAME Information Next two table entries FIRSTNAME LASTNAME NOTIFYURL ORDERDESC ORIGID RECURRINGTYPE Accou
92. tch An authorisation may still exist on the cardholder s account Website Payments Pro Developer s Guide Responses to Transaction Requests 8 RESULT Codes and RESPMSG Values TABLE 8 5 Payflow transaction RESULT values and RESPMSG text Continued RESULT RESPMSG and Explanation 113 Merchant sale total will exceed the sales cap with current transaction ACH transactions only 114 Card Security Code CSC Mismatch An authorisation 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 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 119 General failure within PIM Adapter 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 126 Fraud Protection Services Filter Flagged for review by filt
93. te PayPal automatically gives you the postal address and other customer information to fulfil the order The more convenient it is for your customers to buy from you the more they ll buy PayPal Express Checkout allows customers the option to pay quickly through PayPal and gives your business more benefits PayPal Express Checkout provides these advantages to your customers e Gives buyers more convenience and gets more sales Since your customers simply log in to use information they ve already entered with PayPal they save time by completing transactions in fewer steps e Helps buyers feel safer so they buy more Buyers prefer to pay with PayPal because their customer information is kept safe When they re confident about the security of their information they purchase more With this design you have these advantages e Real time notification of successful payments e Automation of your internal business processes e More advertising opportunities as buyers finish their orders on your website e Notification that the buyer s address is confirmed e Eligibility for coverage under PayPal s Seller Protection Policy Website Payments Pro Developer s Guide 11 12 Website Payments Pro Overview Additional Services Additional Services If you have signed up for the Recurring Billing Service see the Payflow Pro Recurring Billing Service User s Guide It is downloadable from the PayPal Manager Documentation page Business
94. tead For details see Submitting Sale Transactions on page 29 If you need to recharge a credit card and you are not storing the credit card information in your local database you can perform a new reference transaction based on a Sale For details see Recharging to the Same Credit Card Reference Transactions on page 37 Required Authorisation Transaction Parameters To perform an Authorisation transaction you are required to pass the following parameters ACCT AMT EXPDATE Typical Authorisation Transaction Parameter String A typical parameter string passed in an Authorisation transaction 1s the same as a Sale transaction string The only difference is that the TRXTYPE value is A in an Authorisation EXAMPLE 4 3 Typical Authorisation parameter string TRXTY PE A amp TENDER C amp USER SuperMerchant amp PWD SuperUserPassword amp PARTNER PayPal UK amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT1 Reservation amp FIRSTN AME John amp LASTNAME Jones amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CLIENTIP 0 0 0 0 Website Payments Pro Developer s Guide 31 32 Performing Direct Payment Credit Card Transactions Submitting Authorisation Delayed Capture Transactions Required Delayed Capture Transaction Parameters To perform Delayed Capture transaction you are required to pass the following parameter ORIGID Set ORIGID to the PNREF Transaction
95. the AMOUNT 10536 105 Credit error Attempt to credit an authorisation 112 Failed AVS check Use the AMOUNT 10505 114 CVV2 Mismatch Use the AMOUNT 10504 1000 Generic Host Use an AMOUNT other than those listed in this column Processor Error 46 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing This chapter provides guidelines on how to implement PayPal Express Checkout The chapter introduces you to this feature and provides the information you need to get started integrating it into your website application Note If you also plan to use PayPal Direct Payments described in Chapter 4 Performing Direct Payment Credit Card Transactions to process credit cards you must use PayPal Express Checkout together with Direct Payments Direct Payments is not standalone feature In this Chapter e What Is PayPal Express Checkout on page 47 e How PayPal Express Checkout Works on page 48 e Sale and Authorisation Transactions on page 49 e PayPal Express Checkout Sale Transaction Example on page 50 e PayPal Express Checkout Transaction Parameter Descriptions on page 53 What Is PayPal Express Checkout PayPal Express Checkout offers your customers an easy convenient checkout experience It lets them use postal and billing information stored securely at PayPal to check out so they don t have to re enter it on your site From the perspective of website development PayPal
96. the balance TRXTYPE S amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp ORIGID EFHPOD426A51 amp AMT 34 00 RESULT 0 amp PNREF EFHP0D426A53 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZI P N amp CORRELATIONI D 2dc60e253495e Note In the case that your business model uses Authorisation Delayed Capture for all transactions you could have chosen to use partial captures to collect the 34 For an example see Delayed Capture Transaction Capturing Transactions for Lower Amounts on page 33 Using Address Verification Service Address Verification Service AVS consists of the information postal address and postcode AVS compares the submitted billing postal address and postcode with the values on file at the cardholder s bank The response includes values for AVSADDR and AVSZIP Y N or X for the match status of the customer s postal address and postcode Y match N no match X cardholder s bank does not support AVS The AVS result is for advice only Banks do not decline transactions based on the AVS result the merchant makes the decision to approve or decline a transaction AVS is supported by most US banks and some international banks Website Payments Pro Developer s Guide 39 en Performing Direct Payment Credit Card Transactions Card Security Code Validation Nore AVS checks only for a street number match not a street name match so 123 Main Street retu
97. thin the PayPal checkout You have three options e Not request the telephone number default e Request the telephone number as an optional field e Require that the buyer enter his or her telephone number to proceed To set these options log in to your PayPal account click Profile and then click Website Payment Preferences The section to change the default is located at the bottom of the screen 58 Website Payments Pro Developer s Guide PayPal Express Checkout Transaction Processing 6e PayPal Express Checkout Transaction Parameter Descriptions Do Express Checkout Payment Request Parameters In addition to the parameters required by all transaction types described in Chapter 3 Creating a Simple Transaction Request the Do Express Checkout Payment request parameters include e The parameters listed below and described in Table 4 1 Transaction parameters BUTTONSOURCE CUSTOM FREIGHTAMT HANDLINGAMT INVNUM ITEMAMT L AMTn L DESCn L QTYn L TAXAMTn NOTIFYURL ORDERDESC SHIPTOCITY SHIPTOCOUNTRY SHIPTOSTATE SHIPTOSTREET SHIPTOZIP e The required parameters described in Table 6 6 TABLE 6 6 Do Express Checkout Payment request parameters Max Parameter Name Description Required Type Length TOKEN String value returned by Set Express Yes String 20 Checkout response ACTION Is D to indicate this is a Do Express Yes Alpha 1 Checkout Payment request PAYERID Unique PayPal customer account Yes String 13 ident
98. ued Parameter TAXAMT VERBOSITY Max Description Required Type Length Sum of tax for all items in this order No Decimal 10 NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See the CURRENCY entry in this table for details Limitations Must not exceed 10 000 USD in any currency No currency symbol Decimal separator must be a period Do not use comma separators Use 1199 95 not 1 199 95 Either of two values LOW or MEDIUM No Alpha LOW is the default setting normalised values MEDIUM returns the PayPal processor s raw response values See Appendix A Verbosity Viewing Processor Specific Transaction Results a Some transaction types do not require this parameter See Values Required by All Transaction Types on page 17 b If you pass in any of the post to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that 15 SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Additional Parameters by Transaction Type Each Direct Payment credit card transaction type has its own request parameter requirements These are in addition to the parameters required by all transactions described in the following tables in Chapter 3 Creating a Simple Transaction Request e Table 3 1 Connection parameters e Table 3 2 Required transaction parameters Transaction responses
99. ur Website Shopping Cart Postal Info Billing Info Order Review Order Complete Visa 1 2 4 O PayPal Thank You CHECKOUT CONTINUE CONTINUE R 3 4 mS ER PayPal Web Services The numbered steps in the figure are described below 1 On your website the customer chooses to pay with credit card and enters the credit card number and other details 2 The customer reviews the order 3 When your customer clicks Pay to place the order you perform a transaction to request payment and the payment transaction is initiated 4 You transfer your customer to your order confirmation page The button on your website sends the payment request to the server including required information you collected from the customer such as the amount of the transaction the buyer s credit card number expiry date browser IP address and an element that specifies whether this transaction is a final sale complete transaction amount including postage packing and tax or an authorisation for a final amount that you must capture later with a Delayed Capture transaction About Direct Payment Credit Card Processing Direct Payment credit card processing occurs in two steps a real time authorisation and a capture settlement of the funds that were authorised You perform these two steps either as a single Sale transaction or as two types of transactions an Aut
100. verview Direct Payment offers you direct credit card payment processing capability through PayPal For credit card transactions customers can stay on your website as PayPal processes the payment in the background For each payment Direct Payment takes the billing address transaction amount credit card information and item information as inputs Within seconds PayPal returns confirmation that the transaction has been processed If you have signed up for Fraud Protection Services Direct Payment lets you flag potentially fraudulent transactions and provides you with industry standard Address Verification Service and card security code CV V2 responses for each transaction By integrating Direct Payment with PayPal Express Checkout as part of the Website Payments Pro solution you can accept all major payment types including PayPal while working with single provider that processes and manages all your online payments for you IMPORTANT Direct Payment is not a standalone product You are required to use Direct Payment and PayPal Express Checkout together as part of the Website Payments Pro solution See Business Rules on page 12 Direct Payment is not covered by the PayPal Seller Protection Policy SPP PayPal Express Checkout Overview With PayPal Express Checkout a customer selects their products and completes their orders on your website Payment method along with postage and billing details are managed on PayPal s websi
101. word amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 100 00 amp INVNU M 123456789 amp FIRSTNAME John amp LASTNAME Jones amp STREET 5199 MAPLE amp ZIP 94588 Website Payments Pro Developer s Guide Performing Direct Payment Credit Card Transactions d Using Address Verification Service Note the value of the PNREF in the response EXAMPLE 4 14 Response to the Authorisation RESULT 0 amp PNREF EFHP0D426A51 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATCH X amp PPREF 6F5950632E172331R amp CORRELATIONID 3cla7c1c4l1la Step2 Capture the authorised funds for a partial delivery of 66 When you deliver the first 66 worth of product you use normal Delayed Capture transaction to collect the 66 Set ORIGID to the value of PNREF in the original Authorisation EXAMPLE 4 15 Partial capture of the purchase amount TRXTYPE D amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPalUK amp VENDOR SuperMerc hant amp USER SuperMerchant amp ORIGID EFHPOD426A51 amp AMT 66 00 RESULT 0 amp PNREF VXYZ01234568 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZI P N amp CORRELATIONI D 2dc60e253495e Step3 Submit a new Sale transaction of 34 for the rest of the delivery Once you have sent the remainder of the product you can collect the remaining 34 in a Sale transaction that uses the initial Authorisation as a reference transaction EXAMPLE 4 16 New Sale transaction for

Download Pdf Manuals

Related Search

Related Contents

Hitachi Projector ED-AW110N User's Manual  BUB360 - Viborg Havemaskiner  SR600 & SR100 Series Service Manual - Tool  OWNER'S OPERATING MANUAL Router  Epson 475Wi Projector User Manual  

Copyright © All rights reserved. Failed to retrieve file