Home

PayPal Website Payments Pro - 2009 Payflow Edition Developer's Guide

1. 28 Required Credit Transaction Parameters 28 Credit Transaction Parameter Strings 0 0 30 Submitting Void Transactions 30 When To Use Void 30 Required Void Transaction Parameters 31 Example Void Transaction Parameter String 31 Recharging to the Same Credit Card Reference 32 When To Use a Reference 32 Transaction Types that Can Be Used as the Original Transaction 32 Fields Copied From Reference 5 33 Example Reference 33 Using Address Verification Service 34 Example Address Verification Service 34 Example Address Verification Service 34 Card Security Code 35 Example CVV2 35 Example CVV2 35 Chapter 5 Responses to Transaction Requests 37 Contents of a Response to a Credit Card Transaction 37 Address Verification Service Responses From 39 Card Se
2. 15 Typical Sale 16 Formatting 5 16 Chapter 4 Performing Direct Payment Credit Card Transactions 17 About Direct Payment Credit Card Processing 17 Considerations Regarding Your Website Integration 17 Website Payments Pro Payflow Edition Developer s Guide Contents Parameters Used in 5 18 Submitting Sale Transactions 23 When Use a Sale 23 Additional Parameters For Sale 24 Typical Sale Transaction Parameter 5 24 Submitting Authorization Delayed Capture Transactions 24 When To Use Authorization Delayed Capture Transactions 25 Required Authorization Transaction Parameters 25 Typical Authorization Transaction Parameter 0 25 Required Delayed Capture Transaction Parameters 25 Delayed Capture Transaction Capturing Transactions for Lower Amounts 27 Delayed Capture Transaction Capturing Transactions for Higher Amounts 28 Delayed Capture Transaction Error Handling and Retransmittal 28 Submitting Credit Transactions
3. 28 Performing Direct Payment Credit Card Transactions Submitting Credit Transactions 2 Capture the authorized funds for a partial shipment 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 Authorization and set CAPTURECOMPLETE to N TRXTYPE D amp TENDER C amp PWD hant amp USER SuperMerchant This is the response RESULT 0 amp PNREF VXYZ0123 SuperUserPassword amp PARTNER PayPal amp VENDOR SuperMerc amp CAPTURECOMPLETE N amp ORIGID EFHP0D426A51 amp AMT 66 00 4568 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CORRELATI ONID 2dc60e253492e amp PPREF 68W3371331353001F 3 Capture the 34 balance for the rest of the shipment Once you have shipped the remainder of the product you can collect the remaining 34 in a second Delayed Capture transaction setting CAPTURECOMPLETE to Y IRXTYPE D amp TENDER C amp PWD hant amp USER SuperMerchant This is the response RESULT 0 amp PNREF VXYZ0123 SuperUserPassword amp PARTNER PayPal amp VENDOR SuperMerc amp CAPTURECOMPLETE Y amp ORIGID EFHP0D426A51 amp AMT 34 00 4569 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CORRELATI ONID 2dc60e253493e amp PPREF 68W3371331353001F Delayed Capture Transaction Capturing Transaction
4. CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV Country EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS MALVINAS FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY Code GQ ER EE ET FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GG Country GUINEA GUINEA BISSAU GUYANA HATTI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE VATICAN CITY STATE HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN ISLAMIC REPUB LIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA DEMOCRATIC PEOPLE S REPUBLIC OF Code GN GW GY HT HM VA HN HK HU IS IN ID IR IQ IE IM IL IT JM JP JE Aa KP Country KOREA REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE S DEMO CRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMA HIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO Code KR KW KG LA LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX 63 Country
5. FREIGHTAMT Optional Total shipping 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 CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal HANDLINGAMT Optional Total handling 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 CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal DISCOUNT Optional Shipping discount for this order Specify the discount as a positive amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 INSURANCEAMT Optional Total shipping insurance cost for this order Limitations Nine numeric characers plus decimal character No currency symbol Specif
6. Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 104 Timeout waiting for processor response Try your transaction again 105 Credit error Make sure you have not already credited this transaction or that this transaction ID is for a creditable transaction For example you cannot credit an authorization 106 Host not available 107 Duplicate suppression time out 108 Void error See RESPMSG Make sure the transaction ID entered has not already been voided If not then look at the Transaction Detail screen for this transaction to see if it has settled The Batch field is set to a number greater than zero if the transaction has been settled If the transaction has already settled your only recourse is a reversal credit a payment or submit a payment for a credit 109 Time out waiting for host response 110 Referenced auth against order Error 111 Capture error Either an attempt to capture a transaction that is not an authorization transaction type or an attempt to capture an authorization transaction that has already been captured 112 Failed AVS check Address and ZIP code do not match An authorization may still exist on the cardholder s account 113 Merchant sale total will exceed the sales cap with current transaction ACH transactions only 114 Card Security Code CSC Mismatch An authorization may still exi
7. Details of the response message may vary slightly from that shown in the table depending on your SDK integration TABLE 5 14 Communications RESULT values RESULT Description 1 Failed to connect to host 2 Failed to resolve hostname 5 Failed to initialize 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 authorization 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 initialize SSL certificate 48 Website Payments Pro Payflow Edition Developer s Guide Responses to Transaction Requests s RESULT Values and RESPMSG Text TABLE 5 14 Communications RESULT values RESULT Description 23 Host address not specified 24 Invalid transaction type 25 Failed to create a socket 26 Failed to initialize socket layer 27 Parameter list format error invalid name length clause 28 Parameter list format error name 29 Failed to initialize 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 1
8. STATE COUNTRY ZIP Description Optional Product number Limitations 18 characters Optional Line item tax amount Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Optional Your customer Direct Payment session identification token PayPal records this session token as an additional means to detect possible fraud Limitations 64 characters Optional Your URL for receiving Instant Payment Notification IPN about this transaction If you do not specify NOTIFYURL in the request the notification URL from your Merchant Profile is used if one exists Limitations 2048 alphanumeric characters Optional Description of items the customer is purchasing Limitations 127 alphanumeric characters Optional Type of transaction occurrence The values are e F First occurrence e S Subsequent occurrence default Limitations One alpha character Optional Account holder s first name Limitations 25 alpha characters Optional Account holder s first name Limitations 25 alpha characters Optional The cardholder s bill to street address number and street name The STREET address is verified by the address verification service Limitations 100 alphanumeric characters Optional Bill to city address Limitations 40 al
9. The table indicates whether the parameters are required or optional To enable line item support which includes the parameters below you must contact Merchant Technical Support at http www paypal com mts L NAMEn L DESCnN L COSTn L TAXAMIn L OTYn L SKUn TABLE 4 1 Credit card transaction request parameters Parameter TENDER TRXTYPE Description Required The method of payment Values are C Credit card P PayPal Limitations One alpha character Required Indicates the type of transaction to perform Values are S Sale transaction C Credit A Authorization D Delayed Capture V Void N Duplicate transaction NOTE type N transaction represents a duplicate transaction version 4 SDK or HTTPS interface only with a PNREF the same as the original It appears only in the PayPal Manager user interface and will never settle Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions am Parameters Used in Transactions TABLE 4 1 Credit card transaction request parameters Parameter Description ACCT Required Credit card or purchase card number Limitations A maximum of 19 numeric characters This value may not contain spaces non numeric characters or dashes For example ACCT 5555555555554444 EXPDATE Required Expiration date of the credit card Limitations Four numeric characters in mmyy for
10. The transaction has been authorized but requires you to review and to manually accept the transaction before it will be allowed to settle RESULT value 126 is intended to give you an idea of the kind of transaction that is considered suspicious to enable you to evaluate whether you can benefit from using the Fraud Protection Services To eliminate RESULT 126 turn the filters off For more information see the fraud documentation for your payments solution Fraud Protection Services Filter Not processed by filters Fraud Protection Services Filter Declined by merchant after being flagged for review by filters Card has not been submitted for update Data mismatch in HTTP retry request Issuing bank timed out Issuing bank unavailable Reauth error Order error 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 Website Payments Pro Payflow Edition Developer s Guide Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and R
11. 0 0 0 Required Delayed Capture Transaction Parameters To perform a Delayed Capture TRXTYPE D transaction you are required to pass the following parameter Website Payments Pro Payflow Edition Developer s Guide 25 Performing Direct Payment Credit Card Transactions Submitting Authorization Delayed Capture Transactions ORIGID TABLE 4 2 Delayed Capture required parameter Parameter Description ORIGID Required by some transaction types ID of the original transaction that is being referenced This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports Limitations Case sensitive Set ORIGID to the PNREF Transaction ID in PayPal Manager reports value returned from the original transaction In addition if the amount of the capture differs from the amount of the Authorization you also must pass a value for AMT Fields Copied From the Authorization Transaction into the Delayed Capture Transaction The following fields are copied from the Authorization transaction into the 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 EXPDATF These parameters retain their original values TABLE 4 3 Fields copied from Authorization to Delayed Capture transa
12. Codes 64 Country MICRONESIA FEDER ATED STATES OF MOLDOVA REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTI LLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN Code FM MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK Country PALAU PALESTINIAN TERRI TORY OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO Code PW PS PA PG PY PE PH PN PL PR QA RE RO RU RW SH LC PM VC WS SM Country SAO TOME AND PRINC IPE SAUDI ARABIA SENEGAL SERBIA AND MON TENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOMALIA SOUTH AFRICA SOUTH GEORGIA AND THESOUTHSANDWICH ISLANDS SPAIN SRILANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUB LIC TAIWAN PROVINCE OF CHINA TAJIKISTAN Code ST SA SN CS SC SL SG SK SI SB SO ZA GS ES LK SD SR SJ SZ SE CH SY TW TJ Country TANZANIA UNITED REPUBL
13. Response X All other X PNREF Value The PNREF is a unique transaction identification number issued by PayPal that identifies the transaction for billing reporting and transaction data purposes The PNREF value appears in the Transaction ID column in PayPal Manager reports e The PNREF value is used as the ORIGID value original transaction ID in Delayed Capture transactions TRXTYPE D Credits TRXTYPE C Inquiries and Voids TRXTYPE V e The PNREF value is used as the ORIGID value original transaction ID value in reference transactions for Authorization TRXTYPE A and Sale TRXTYPE S NOTE The PNREF is also referred to as the Transaction ID in PayPal Manager PNREF Format The PNREF is a 12 character string of printable characters for example e VADEOB248932 e ACRAF23DB3C4 Printable characters also include symbols other than letters and numbers such as the question mark A PNREF typically contains letters and numbers only The PNREF in a transaction response tells you that your transaction is connecting to PayPal Website Payments Pro Payflow Edition Developer s Guide 41 Responses to Transaction Requests RESULT Values and RESPMSG Text RESULT Values and RESPMSG Text The RESULT parameter and value is the first name value pair returned in the response string The value of RESULT indicates the overall status of the
14. Website Payments Pro Payflow Edition uses the Payflow gateway and Payflow Pro SDK to send transactions to PayPal for processing This product offers two payment solutions PayPal Direct Payment to process credit card transactions and PayPal Express Checkout to process PayPal transactions Website Payments Pro Payflow Edition Developer s Guide introduces transaction processing through the Payflow gateway and describes how to integrate Direct Payment credit card processing Direct Payment credit card processing is not a standalone feature You must use Direct Payment together with Express Checkout Use this guide along with the companion guide Express Checkout for Payflow Pro for details on integrating Express Checkout Intended Audience This guide is written for merchants who have signed up through PayPal Manager to use PayPal as their processor for handling payment transactions on their website This guide assumes that its readers e Are experienced web or application developers e Have a background payments services Related Documentation For additional Payflow information see the following related documentation e Express Checkout for Payflow Pro for integrating Express Checkout as a payment solution Use this guide in conjunction with the Express Checkout guide for complete information on Express Checkout transaction processing e PayPal Manager online help for processing transactions manually issuing cr
15. of the product or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice Contents Preface About This Guid sa s res Emo XS hom X RR w s US MO sN Intended Audience a sss ss Related Documentation How to Contact Customer Support Revision History e ease aye Quan eee SEE Ob ST anb ACA ke RD ee Chapter 1 Introduction About Website Payments Pro Payflow Edition Payflow SDK Version Host Addresses How Direct Payment Processing 10 Chapter 2 Downloading Installing and Activating 11 Supported 11 Preparing the Payflow Client Application 11 Activating Your Payflow Pro Account 12 Chapter 3 Simple Payflow 1 Transaction 5 5 13 Request Contents 2 a 13 Data Modes for 13 Connection Parameters 14 User 15 Sale Transaction
16. transaction attempt e value of zero indicates that no errors occurred and the transaction was approved e A value less than 0 indicates that a communication error occurred In this case no transaction is attempted e value greater than 0 indicates a decline or error except in the case of RESULT 104 See the table below The response message RESPMSG provides a brief description for decline or error results RESULT Values for Transaction Declines or Errors For non zero RESULT values the response string includes a RESPMSG name value pair The exact wording of the RESPMSG shown in bold may vary Sometimes a colon appears after the initial RESPMSG followed by more detailed information When interpreting RESULT values for the PayPal processor note the following e When RESULT 0 warning information may be returned that is useful to the request applicaton See the PayPal API documentation on Developer Central for detailed information on corrective actions e When RESULT 104 you must log in to the PayPal website to determine if the transaction actually went through If the transaction does not appear in the History section you should retry it TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 0 Approved NOTE PayPal processor Warning information may be returned that may be useful to the request applicaton See the PayPal API documentation on the PayPal
17. transactions when to use 30 website integration considerations 17 Y Yen 59 Z ZIP parameter 22 ZIPparameter 24 Zloty 59 Website Payments Pro Payflow Edition Developer s Guide
18. trying to process a tender type such as Discover Card but you are not set up with your merchant bank to accept this card type e You are trying to process a tender type such as Discover Card but you are not set up with your merchant bank to accept this card type e You trying to process an Express Checkout transaction when your account is not set up to do so Contact your account holder to have Express Checkout added to your account Invalid vendor account Login information is incorrect Verify that USER VENDOR PARTNER and PASSWORD have been entered correctly VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user All fields are case sensitive Insufficient partner permissions Insufficient user permissions Invalid XML document This could be caused by an unrecognized XML tag or a bad XML format that cannot be parsed by the system Duplicate transaction Error in adding the recurring profile Error in modifying the recurring profile Error in canceling 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 Website Payments Pro Payflow Edition Developer s Guide
19. txt file includes integration information and samples that illustrate how to use the Payflow client application in your development environment Website Payments Pro Payflow Edition Developer s Guide 11 r Downloading Installing and Activating Activating Your Payflow Pro Account Activating Your Payflow Pro Account When you are ready to activate your Payflow Pro account to begin submitting live transactions follow these steps 1 Log in to PayPal Manager at https manager paypal com 2 Click ActivateYour Account and follow the on screen instructions 3 Change the URL within your web or desktop application to point to the live Payflow servers For details on Payflow server URLs see Host Addresses on page 9 12 Website Payments Pro Payflow Edition Developer s Guide Simple Payflow Transaction All Payflow transactions include a common set of required parameters 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 normalized information if you are looking for this kind of information VERBOSITY is described in detail in Appendix A Verbosity Viewing Processor Specific Transaction Results Transaction Requests Request Contents transaction request includes e Connection parameters e User para
20. 0 30 31 COUNTRY 22 33 CURRENCY 19 CUSTCODE 26 30 31 CUSTIP 19 24 26 30 31 CUSTOM 20 CUSTREF 20 CVV2 24 35 CVV2MATCH 40 DATE TO SETTLE 56 EMAIL 20 26 30 31 EXPDATE 16 19 24 25 26 29 30 31 33 FIRSTNAME 22 24 26 30 31 33 FREIGHTAMT 21 26 30 31 HANDLINGAMT 21 HOSTADDRESS 14 HOSTCODE 55 HOSTPORT 14 INVNUM 20 26 30 31 ITEMAMT 20 L COSTn 21 L DESCn 21 L QTYn 21 L SKUn 22 L TAXAMTn 22 LASTNAME 22 24 26 30 31 33 MERCHANTSESSIONID 22 Website Payments Pro Payflow Edition Developer s Guide NOTIFYURL 22 ORDERDESC 22 ORIGID 26 28 29 31 41 PARMLIST 14 PARTNER 15 PAYMENTTYPE 39 PNREF 26 28 29 31 41 PONUM 26 30 31 PROCAVS 55 PROCCARDSECURE 55 PROCCVV2 55 PROXYADDRESS 14 PROXYLOGON 14 PROXYPASSWORD 14 PROXYPORT 14 PWD 15 RECURRINGTYPE 22 RESPMSG 42 RESPTEXT 55 RESULT 42 48 SETTLE DATE 56 SHIPTOCITY 23 26 30 31 SHIPTOCOUNTRY 23 26 30 31 SHIPTOFIRSTNAME 26 30 31 SHIPTOLASTNAME 26 30 31 SHIPTOSTATE 23 26 30 31 SHIPTOSTREET 23 26 30 31 SHIPTOZIP 23 26 30 31 STATE 22 26 30 31 33 STREET 22 26 30 31 33 34 TAXAMT 20 26 30 31 TENDER 18 TIMEOUT 14 TRANSSTATE 56 TRXTYPE 18 23 24 25 28 30 41 USER 15 VENDOR 15 VERBOSITY 13 14 20 55 ZIP 22 24 26 30 31 33 34 payflowpro paypal com 9 PAYMENTTYPE parameter 39 PayPal Developer Central 7 PayPal supported currencies 59 Peso 59 Phillippine Peso 59 pilot payflow
21. 00 Parameter list cannot be empty 103 Context initialization 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 initializing from message file lt Details of the error message gt 113 Unable to round and truncate the currency value simultaneously Website Payments Pro Payflow Edition Developer s Guide 49 Responses to Transaction Requests RESULT Values and RESPMSG Text 50 Website Payments Pro Payflow Edition Developer s Guide Testing Credit Card Transactions To test your application direct all transactions to the host address for testing For details see Host Addresses on page 9 Transactions directed to the testing URL are processed through PayPal s simulated payment network enabling you to test the configuration and operation of your application or storefront no money changes hands You must activate your account and configure your application for live transactions before accepting real orders Testing Guidelines e While testing use only the credit card numbers listed in this chapter Other numbers produce an error e Expiration 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 Info gt Pr
22. ATI ONID 2dc60e253495e amp PPREF 68W3371331353001F Using Address Verification Service To qualify for the lowest bank rate you must pass address verification service information street address and ZIP postal code Address Verification Service compares the submitted billing street address and ZIP code with the values on file at the cardholder s bank The response includes values for AVSADDR AVSZIP Y N or X for the match status of the customer s street address and ZIP code Y match N no match X cardholder s bank does not support Address Verification Service The Address Verification Service result is for advice only Banks do not decline transactions based on the Address Verification Service result the merchant makes the decision to approve or decline a transaction Address Verification Service is supported by most U S banks and some international banks Note Address Verification Service checks only for a street number match not a street name match so 123 Main Street returns the same response as 123 Elm Street The International Address Verification Service IAVS response indicates whether the Address Verification Service response is international Y USA N or cannot be determined X SDK version 3 06 or later is required Example Address Verification Service Request This example request include the address verification service request
23. Australian Dollar Canadian Dollar Euro Japanese Yen Pound Sterling U S Dollar Website Payments Pro Payflow Edition Developer s Guide 59 Currency Codes 60 Website Payments Pro Payflow Edition Developer s Guide Note This table lists country codes Country Codes defined by ISO 3166 1 Table 1 Country Codes Country AFGHANISTAN LAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BAR BUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS Code AF AX AL DZ AS AD AO Al AQ AG AR AM AW AU AT AZ BS BH BD BB Country BELARUS BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZE GOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS Code BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI CM CA CV KY 61 Country Codes 62 Country CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS KEELING ISLANDS COLOMBIA COMOROS CONGO CONGO THE DEMO CRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR Code CF TD CL CN CX CC CO KM CG CD
24. Card Reference Transactions e Credit Fields Copied From Reference Transactions The following fields are copied from the reference transaction into the new Sale or Authorization transaction if 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 TABLE 4 8 Fields copied to new transaction ACCTTYPE STREET ACCT CITY EXPDATE STATE FIRSTNAME ZIP ASTNAME COUNTRY Example Reference Transaction In this example you authorize an amount of 100 for a shipment and charge 66 for the first partial shipment using a normal Delayed Capture transaction You charge the 34 for the final part of the shipment using a reference transaction to draw credit card and shipping address information from the initial Authorization transaction This example procedure creates a reference transaction 1 Submit the initial transaction such as an Authorization You use an Authorization transaction for the full amount of the purchase of 100 IRXTYPE A amp TENDER C amp PWD password amp PARTNER partner amp VENDOR vendor amp USER user amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 100 00 amp INVNUM 123456789 amp STREET 51 99 MAPLE amp ZIP 94588 Note the value of the PNREF in the response RESULT 0 amp PNREF EFHPOD426A51 amp RESPMSG Approved amp A
25. ESPMSG Text RESULT RESPMSG and Explanation 1013 Buyer Authentication Service unavailable 1014 Buyer Authentication Service Merchant is not enrolled for Buyer Authentication Service 3 D Secure 1016 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 1017 Buyer Authentication Service 3 D Secure error response is invalid An error response is received and the response is not well formed for a Validate Authentication transaction 1021 Buyer Authentication Service Invalid card type 1022 Buyer Authentication Service Invalid or missing currency code 1023 Buyer Authentication Service merchant status for 3D secure is invalid 1041 Buyer Authentication Service Validate Authentication failed missing or invalid PARES 1042 Buyer Authentication Service Validate Authentication failed PARES format is invalid 1043 Buyer Authentication Service Validate Authentication failed Cannot find successful Verify Enrollment 1044 Buyer Authentication Service Validate Authentication failed Signature validation failed for PARES 1045 Buyer Authentication Service Validate Authentication failed Mismatched or invalid amount in PARES 1046 Buyer Authentication Service Validate Authentication failed Mismatched or invalid acquirer in PARES 1047 Buyer Authentication Service Valid
26. Exact Match Y Yes Z Zip All other AVSADDR x 2K lt 2 AVSZIP x lt lt lt Card Security Code Results The CVV2MATCH parameter returns Y N or X The CVV2MATCH parameter returns Y N or X or a processor specific response Normalized Results The table below shows the detailed results returned by the PayPal processor for card security codes If you want to obtain the PayPal processor value set the VERBOSITY parameter to TABLE 5 11 CVV2MATCH response values MEDIUM The processor value is returned in the PROCCVV2 response parameter 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 40 Website Payments Pro Payflow Edition Developer s Guide Responses to Transaction Requests PNREF Value PayPal Card Security Code Results The table below shows the detailed results returned by the PayPal processor for card security codes If you want to obtain the PayPal processor value set the VERBOSITY parameter to MEDIUM The processor value is returned in the PROCCVV2 response parameter TABLE 5 12 Card security code response code mapping PayPal Processor CVV2 PayPal Processor Code Code Description PROCVV2MATCH M Match Y N No Match N P Not Processed X S Service Not Supported X U Unavailable X No
27. IC OF THAILAND TIMOR LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE UNITED ARAB EMIR ATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS BRIT ISH Code TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN VG 65 Country Codes 66 Country VIRGIN ISLANDS U S WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE Code VI EH YE ZM ZW Index A ACCT parameter 19 ACCTTYPE parameter 19 ADDLMSGS parameter 55 address verification service 34 AMT parameter 19 APIs documentation 11 downloading 11 application testing 51 Australian Dollar 59 authorization delayed capture transactions when to use 25 Baht 60 BATCHID parameter 56 Brazilian Real 59 BUTTONSOURCE parameter 19 C Canadian Dollar 59 CAPTURECOMPLETE parameter 20 27 CITY parameter 22 COMMENT I parameter 19 COMMENT parameter 24 COMMENT parameter 20 COUNTRY parameter 22 credit transaction type 28 currency code format 19 20 21 currency codes 19 59 CURRENCY parameter 19 CUSTIP parameter 19 CUSTIPparameter 24 CUSTOM parameter 20 Customer Support 18 CUSTREF parameter 20 CVV2 parameter 24 CVV2 parameterPayflow parameters CVV2 20 CVV2MATCH parameter 40 Czech Koruna 59 D Dan
28. OD426838 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATC H X amp PPREF 68W3371331353001F amp CORRELATIONID 2e52df7ddf292 2 Perform the Delayed Capture transaction Set ORIGID to the PNREF value returned in the original Authorization 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 Capture 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 Delayed Capture Transaction IRXTYPE D amp TENDER C amp USER SuperMerchant amp VENDOR SuperMerchantPARTNER PayPal amp PWD SuperUserPassword TENDER C amp COMMENT 1 Reservat ion amp ORIGID EFHP0D426838 Example Delayed Capture Response RESULT 0 amp PNREF EFHPOD42687C amp RESPMSG Approved amp CORRELATIONID b5689409e279f amp PPREF 68W3371331353001F amp FEEAMT 0 56 amp PAYMENTTYPE instant amp PENDINGREASON c ompleted Delayed Capture Transaction Capturing Transactions for Lower Amounts You can perform a Delayed Capture transaction for an amount lower than the original Authorization amount useful for example when you make a partial shipment To perform a partial capture programmatically using the Payflow SDK se
29. OUNT e 10548 e 10549 52 Website Payments Pro Payflow Edition Developer s Guide TABLE 6 2 Obtaining PayPal result code Testing Credit Card Transactions Testing Result Code Responses Result Definition 7 Field format error 12 Declined 13 Referral 23 Invalid account number How to test 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 Use any of these as AMOUNT 10417 15002 15005 15006 15028 15039 10544 10545 10546 Use the AMOUNT 10422 Use any of these as AMOUNT 10519 10521 10522 10527 10535 10541 10543 Website Payments Pro Payflow Edition Developer s Guide 53 54 Testing Credit Card Transactions Testing Result Code Responses TABLE 6 2 Obtaining PayPal result code Result 24 30 105 112 114 1000 Definition Invalid expiration date Duplicate Transaction Credit error Failed AVS check CVV2 Mismatch Generic Host Processor Error How to test Use any of these as AMOUNT e 10502 e 10508 Use the AMOUNT 10536 Attempt to credit an authorization Use the AMOUNT 10505 Use the AMOUNT 10504 Use an AMOUNT other than those listed in this column Website Payments Pro Payflow Edition Developer s Guide Verbosity Viewing Processor Specific Transaction Results Transaction results especially values for declines a
30. PROCCVV2 char 1 CV V2 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 Payflow Edition Developer s Guide 55 A Verbosity Viewing Processor Specific Transaction Results Supported Verbosity Settings TABLEA 1 Voerbosity settings Continued Field Name Type Length Description TRANSSTATE Integer 10 State of the transaction The values are 0 General succeed state I General error state 3 Authorization 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 Authorization captured once an authorization type transaction is captured its TRANSSTATE becomes 9 10 Capture failed an error occurred while trying to capture an authorization 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 22 Unsettled transaction because of incorrect account information 14 For various reasons the batch containing this transaction failed settlement 15 Settlement incomplete due to a charge back 106 Unknown Status Transacti
31. PTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Limitations 10 character string Optional Ship to country code See Appendix C Country Codes NOTE If you pass in any of the ship to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that is SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Limitations Two alpha characters Optional U S ship to zip code or other country specific postal code NOTE If you pass in any of the ship to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that is SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Limitations 20 character string Submitting Sale Transactions The Sale transaction TRXTYPE S charges the specified amount including shipping handling and tax 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 When To Use a Sale Transaction A Sale transaction is best suited to businesses that provide immediate fulfillment for their products or services If your business does not provide immediate fulfillment then credit card Website Payments Pro Payflow Edition Developer s Guide 23 24 Performing Direct Payment Credit Card Transactions Submitting Autho
32. PayPal Website Payments Pro Payflow Edition Developer s Guide PayPal Website Payments Pro Payflow Editiion Developer s Guide Document Number 200016 en_US 200911 2009 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal Europe S r l et Cie 5 Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use
33. TREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp BILLTOCOUNTRY US amp CVV2 123 amp CUSTIP 0 0 0 0 Note that besides the required Sale transaction parameters the above string includes other Payflow Pro parameters typically included in a credit card Sale transaction request When the transaction completes the Payflow server returns a response string made up of name value pair response parameters If the transaction is successful a RESULT value of 0 is returned The value of PNREF identifies the transaction in future requests and RESPMSG is a string indicating whether the transaction was approved This is an example response to a credit card Sale transaction request RESULT 0 amp PNREF VXYZ01234567 amp RESPMSG APPROVED amp AVSADDR Y amp AVSZIP N amp IAVS Y amp CVV2 MATCH Y amp PPREF 68W3371331353001F amp CORRELATIONID 2dc60e253495 Formatting Transactions For details on how to format a transaction based on the above information see the examples and the supporting documentation provided with your SDK 16 Website Payments Pro Payflow Edition 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 credit card Direct Payment credit card processing is no
34. VSADDR N amp AVSZIP Y amp CVV2MATC H X amp PPREF 6F S 950632E172331R amp CORRELATIONID 3cla7clc4lla 2 Capture the authorized funds for a partial shipment of 66 When you deliver the first 66 worth of product you use a normal Delayed Capture transaction to collect the 66 Set ORIGID to the value of PNREF in the original Authorization See Required Delayed Capture Transaction Parameters on page 25 TRXTYPE D amp TENDER C amp PWD pas sword amp PARTNER partner amp VENDOR vendor amp USER user amp ORIGID VXYZ01234567 SAMT 66 00 This is the response RESULT 0 amp PNREF VXYZ01234568 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CORRELATI ONID 2dc60e253495e amp PPREF 68W3371331353001F Website Payments Pro Payflow Edition Developer s Guide 33 BEER Performing Direct Payment Credit Card Transactions Using Address Verification Service 3 Submit a new Sale or Authorization Delayed Capture transaction of 34 for the rest of the shipment Once you have shipped the remainder of the product you can collect the remaining 34 in a Sale transaction that uses the initial Authorization as a reference transaction IRXTYPE S amp TENDER C amp PWD password amp PARTNER partner amp VENDOR vendor amp USER user amp ORIGID VXYZ01234567 amp AMT 34 00 This is the response RESULT 0 amp PNREF EFHPOD426A53 amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CORREL
35. Viewing Processor Specific Transaction Results Using Special Characters in Values Because the ampersand amp and equal sign characters have special meanings in the PARMLI ST name value pairs like the following examples not valid Website Payments Pro Payflow Edition Developer s Guide Simple Payflow Transaction GEN Sale Transaction Example NAME Ruff amp Johnson COMMENT1 Level 5 To use special characters in the value of a name value pair use a 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 COMMENT1 7 Level 5 NOTE Quotation marks are not allowed even if you use a length tag User Parameters All Payflow Pro transactions require the user parameters described below TABLE 3 2 User parameters Parameter Description USER Required If you set up one or more additional users on the account this value is the ID of the user authorized to process transactions If however you have not set up additional users on the account USER has the same value as VENDOR Limitations Sixty four alphanumeric case sensitive characters VENDOR Required Your merchant login ID that you created when you registered for the account Limitations Sixty four alphanumeric case sensitive characters PARTNER Required The ID provided to you by th
36. ain incremental sales from PayPal s growing base of users e Direct Payment credit card processing which enables you to accept credit card payments directly on your website PayPal remains invisible so you control the customer experience By integrating Direct Payment credit card processing with Express Checkout as part of the Website Payments Pro Payflow Edition solution you can accept all major payment types including PayPal while working with a single provider that processes and manages all of your online payments Payflow SDK Version To determine the version of the Payflow SDK you are using view a transaction in PayPal Manager In Transaction Details check the value of Client Version A value of 3x means you are using a version 3 V3 SDK a value of 4x means you are using a version 4 V4 SDK Host Addresses Use the following host addresses for the Payflow V4 SDK e Forlive transactions use payflowpro paypal com e Fortesting purposes use pilot payflowpro paypal com Website Payments Pro Payflow Edition Developer s Guide Introduction How Direct Payment Processing Works How Direct Payment Processing Works Figure 1 1 illustrates the Direct Payment credit card processing flow For credit card transactions customers can stay on your website as PayPal processes the payment in the background FIGURE 1 1 Direct Payment credit card processing Your Website Shopping Cart CHECKOUT Shipping Info Bi
37. alue used for tracking this Direct Payment transaction Character length and limitations 13 alphanumeric characters Address Verification Service Responses From PayPal The table below compares the detailed response returned by the PayPal processor for address verification to the normalized response value Y N or X returned in the AVSADDR and AVSZIP response parameters If you want to obtain the PayPal processor value set the VERBOSITY parameter to MEDIUM With this setting the processor value is returned in the PROCAVS response parameter For details on VERBOSITY see Appendix A Verbosity Viewing Processor Specific Transaction Results TABLE 5 10 Address Verification Service response value mapping PayPal Processor Address Verification Service Code Meaning AVSADDR AVSZIP A Address Y N 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 X X I International Unavailable X X N No N N P Postal International Z N Y R Retry X X S Service not Supported X X Website Payments Pro Payflow Edition Developer s Guide 39 5 Responses to Transaction Requests Card Security Code Results TABLE 5 10 Address Verification Service response value mapping PayPal Processor Address Verification Service Code Meaning U Unavailable w Whole Zip X
38. ansaction The quotation marks at the beginning and end are required The following is an example TRXTYPE S amp TENDER C amp PARTNER PayPal amp VENDOR SuperMerchant amp USER Sup erMerchant amp PWD SuperUserPassword amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 The content of the PARMLIST varies by the type of transaction being processed For example a Void transaction requires a different set of parameters than a Sale Required 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 Optional Proxy server address Use the PROXY parameters for servers behind a firewall Your network administrator can provide the values Optional Proxy server port Optional Proxy server logon ID Optional Proxy server logon password PARMLIST Syntax Guidelines Follow these guidelines when creating the PARMLIST Spaces are allowed in values Enclose the PARMLIST in quotation marks Do not place quotation marks within the body of the PARMLIST Separate Set the VI all name value pairs in the PARMLIST using an ampersand amp response ERBOSITY transaction parameter to MEDIUM default is LOW if you want the to return more detailed information For details see Appendix A Verbosity
39. ate Authentication failed Mismatched or invalid Merchant ID in PARES 1048 Buyer Authentication Service Validate Authentication failed Mismatched or invalid card number in PARES 1049 Buyer Authentication Service Validate Authentication failed Mismatched or invalid currency code in PARES 1050 Buyer Authentication Service Validate Authentication failed Mismatched or invalid XID in PARES 1051 Buyer Authentication Service Validate Authentication failed Mismatched or invalid order date in PARES Website Payments Pro Payflow Edition Developer s Guide 47 Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 1052 Buyer Authentication Service Validate Authentication failed This PARES was already validated for a previous Validate Authentication transaction RESULT Values for Communications Errors A RESULT value less than zero indicates that a communication error occurred In this case no transaction is attempted A value of 1 or 2 usually indicates a configuration error caused by an incorrect URL or by configuration issues with your firewall 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
40. ction ACCT AMT CITY COMMENT 1 COMMENT2 COUNTRY CUSTCODE CUSTIP EMAIL EXPDATE FIRSTNAME FREIGHTAMT INVNUM LASTNAME NOTE PHONEUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET TAXAMT ZIP To perform the Delayed Capture 1 Perform the Authorization transaction The Authorization transaction uses the same parameters as Sale transactions except that the transaction type is A The return data for an Authorization transaction is the same as for a Sale transaction To capture the authorized funds perform a Delayed Capture transaction that includes the value returned for PNREF as described in Step 2 below Example Authorization only Transaction IRXTYPE A amp TENDER C amp USER user amp VENDOR vendor amp PARTNER partner amp PWD password amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 9 06COMMENT1 Reservat ion amp FIRSTNAM 26 Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions Submitting Authorization Delayed Capture Transactions E 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 Example Authorization Response RESULT 0 amp PNREF EFHP
41. curity Code 5 5 40 Normalized Results 40 PayPal Card Security Code 41 PNREF Value 52525 E A BEG ed drag l 41 4 Website Payments Pro Payflow Edition Developer s Guide Contents PNREF 41 RESULT Values and RESPMSG 42 RESULT Values for Transaction Declines or 42 RESULT Values for Communications Errors 48 Chapter 6 Testing Credit Card Transactions 51 Testing 5 51 Credit Card Numbers Used for Testing 51 Testing Result Code lt 52 Appendix Verbosity Viewing Processor Specific Transaction Results 55 Supported Verbosity Settings 55 Changing the Verbosity Setting 57 Appendix B Currency 59 Appendix C Country Codes 61 Index 2 2 2 2 2 2 52 2 2 5252 25 07 Website Payments Pro Payflow Edition Developer s Guide 5 Contents 6 Website Payments Pro Payflow Edition Developer s Guide Preface About This Guide
42. d parameter Parameter Description ORIGID Required by some transaction types ID of the original transaction that is being referenced This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports Limitations Case sensitive Set ORIGID to the PNREF Transaction ID in PayPal Manager reports value returned for the original transaction 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 a new value for any of these parameters when submitting the Void transaction then the new value is used Exceptions are ACCT EXPDATE and SWIPE These parameters retain their original values TABLE 4 7 Fields copied from original transaction into the Void transaction ACCT AMT CITY COMMENT1 COMMENT2 COUNTRY CUSTCODE CUSTIP EMAIL EXPDATE FIRSTNAME FREIGHTAMT INVNUM LASTNAME NOTE PHONEUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET TAXAMT ZIP Example Void Transaction Parameter String This is an example Void transaction parameter string TRXTYPE V amp TENDER C amp PARTNER PayPal amp VENDOR SuperMerchant amp USER SuperMerchant am
43. e Authorization Delayed Capture Transactions If your business does not provide immediate fulfillment of products or services you should use this two stage transaction solution 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 fulfillment you can use a simple Sale transaction instead For details see Submitting Sale Transactions on page 23 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 32 Required Authorization Transaction Parameters To perform an Authorization transaction you are required to pass the following parameters e ACCT e AMT e EXPDATE Typical Authorization Transaction Parameter String A typical parameter string passed in an Authorization transaction is the same as a Sale transaction string The only difference is that the TRXTYPE value is A in an Authorization TRXTYPE A amp TENDER C amp USER user amp PWD password amp PARTNER partner amp ACCT 510510510510 5100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT1 Reservat ion amp FIRSTNAME John amp LASTNAME Jo nes amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CLIENTIP 0
44. e authorized PayPal Reseller who registered you for the Payflow SDK If you purchased your account directly from PayPal use PayPal Limitations Sixty four alphanumeric case sensitive characters PWD Required The password that you defined while registering for the account Limitations Six to thirty two alphanumeric case sensitive characters Sale Transaction Example In addition to the connection and user parameters each transaction type has additional parameter requirements and can include a number of optional parameters as well The transaction parameters common to all processors are described in detail in Table 4 1 on page 26 To perform a credit card Sale transaction you are required to pass the following parameters e TRXTYPE The type of the transaction such as S for Sale TENDER The method of payment such as C for credit card e ACCT The buyer s credit card number e AMT The amount of the sale Website Payments Pro Payflow Edition Developer s Guide 15 Simple Payflow Transaction Formatting Transactions e EXPDATE The expiration date of the credit card Typical Sale Transaction The following is a typical request transaction string for a Sale transaction IRXTYPE S amp TENDER C amp USER SuperMerchant amp PWD SuperUserPassword amp PARTNER PayPal amp ACCT 5105105105105100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT 1 Reservat ion amp FIRSTNAME John amp LASTNAME Jones amp S
45. edit cards and generating reports e For additional help see the Help Center at the following URL https www paypal com us cgi bin helpweb cmd help The Sample Code and Documentation section of the PayPal Developer Central home page provides a link to the Payflow documentation Website Payments Pro Payflow Edition Developer s Guide ES How to Contact Customer Support How to Contact Customer Support For problems with transaction processing or your connection to the server contact Customer Support by opening a ticket on the under Contact Support tab at http www paypal com mts Revision History Revision history for PayPal Website Payments Pro Payflow Editiion Developer s Guide TABLE 1 1 Hevision history Date November 2009 October 2009 March 2009 November 2008 June 2008 March 2008 February 2008 November 2007 Description Updated currency codes table Updated currency codes Edits for technical accuracy Added credit card line item details parameters to Chapter 4 Performing Direct Payment Credit Card Transactions e Moved coverage of Express Checkout originally in this guide to a separate document Express Checkout for Payflow Pro e Removed Enroute and Jal from credit card ACCTTYPE description e Added PPREF to transaction responses e Updated table of RESULT values and RESPMSG text e Added Currency Codes appendix Updated Preface Made CURRENCY a required parameter Added co
46. ines and parameter requirements for Credit transactions differ depending on whether or not non referenced credits are allowed Non Referenced Credits Not Allowed When non referenced credits are not allowed the setting recommended by PayPal then Credit transactions are permitted only against existing Sale Delayed Capture and Voice Authorization transactions To submit a Credit transaction when non referenced credits are not allowed you must pass the following parameter ORIGID TABLE 4 4 Credit required parameter Parameter Description ORIGID Required by some transaction types ID of the original transaction that is being referenced This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports Limitations Case sensitive 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 If you do not specify an amount then the amount of the original transaction is credited to the cardholder Non Referenced Credits Allowed When non referenced credits are allowed then Credit transactions are permitted in any amount up to the transaction limit for the credit card account that you specify To submit a Credit transaction when non referenced credits are not allowed you must pass values for the following parameters e ACCT e e AMT IMPORTANT The default
47. ion string non referenced credits not allowed TRXTYPE C amp TENDER C amp PARTNER partner amp VENDOR vendor amp USER user amp PNWD password amp ORI GID EFHP0D426A62 This is an example Credit transaction string non referenced credits allowed RXTYPE C amp TENDER C amp PARTNER partner amp VENDOR vendor amp USER user amp PWD password amp ACC T 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 Submitting Void Transactions When To The Void transaction TRXTYPE V prevents a transaction from being settled As part of its internal process PayPal makes reasonable effort to process authorization reversals for void transactions for debit and credit cards For more information on authorization reversals see http en wikipedia org wiki Authorization hold Use a Void Transaction Follow these guidelines e You void Delayed Capture and Authorization transactions You cannot void a Void transaction e You can only use a Void transaction on a transaction that has not yet settled To refund customer s money for a settled transaction you must submit a Credit transaction Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions am Submitting Void Transactions Required Void Transaction Parameters To submit a Void transaction you must pass the following parameter ORIGID TABLE 4 6 Void require
48. ish Krone 59 DATE TO SETTLE parameter 56 documentation API 11 Dollar 59 60 downloading APIs 11 duplicate transactions 18 E EMAIL parameter 20 Euro 59 EXPDATE parameter 19 F firewalls configuring 11 FIRSTNAME parameter 22 FIRSTNAMEparameter 24 Forint 59 Franc 59 fraud detection 22 FREIGHTAMT parameter 21 H HANDLINGAMTparameter 21 Hong Kong Dollar 59 HOSTCODE parameter 55 Hungarian Forint 59 Instant Payment Notification 22 INVNUM parameter 20 Israeli New Sheqel 59 ITEMAMT parameter 20 J Japanese Yen 59 K Koruna 59 Krona 59 Krone 59 L L_COSTn parameter 21 L DESCnparameter 21 L QTYn parameter 21 L SKUn parameter 22 L TAXAMTn parameter 22 LASTNAME parameter 22 LASTNAMEparameter 24 length tags 15 libraries NET 9 libraries Java 9 live transactions 12 live transactions host address 9 Malaysian Ringgit 59 MERCHANTSESSIONID parameter 22 Mexican Peso 59 N New Dollar 59 New Sheqel 59 New Zealand Dollar 59 Norwegian Krone 59 NOTIFYURL parameter 22 O online help 7 operation testing 51 68 ORDERDESC 22 ORDERDESC parameter 22 ORIGID parameter 26 29 31 P PARTNER parameter 15 Payflow documentation 7 Payflow parameters ACCT 15 19 24 25 26 29 30 31 33 ACCTTYPE 19 33 ADDLMSGS 55 AMT 15 19 24 25 26 29 30 31 AVSADDR 34 AVSZIP 34 BATCHID 56 BUTTONSOURCE 19 CAPTURECOMPLETE 20 27 CITY 22 26 30 31 33 COMMENT 19 24 26 30 31 COMMENT 2
49. ld helps to track transaction information The customer s street address STREET and ZIP should be passed to use the Address Verification Service CVV2 is needed for card security code validation For details on Address Verification Service and card security code see the following sections e Using Address Verification Service on page 34 e Card Security Code Validation on page 35 Submitting Authorization Delayed Capture Transactions An Authorization 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 Authorization to capture the original Authorization amount You can perform up to 10 partial captures for a single authorization 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 Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions Submitting Authorization Delayed Capture Transactions Because Visa and MasterCard regulations prohibit capturing credit card transaction funds until a product or service has shipped to the buyer most processing networks implement an Authorization transaction followed by a Delayed Capture transaction When To Us
50. line help for instructions on setting reference transactions and other security features Sale and Authorization 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 Authorization transaction With the exception of dollar amount data which triggers a filter if out of range reference transactions are not screened by fraud filters I MPORTANT 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 Transaction Types that Can Be Used as the Original Transaction You can reference the following transaction types to supply data for a new Sale or Authorization transaction e Sale e Authorization To capture the funds for an approved Authorization transaction be sure to perform a Delayed Capture transaction not a Reference transaction e Void e Delayed Capture Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions am Recharging to the Same Credit
51. lling Info Visa 1 MC O PayPal CONTINUE CONTINUE The numbers in the flow identify these events Order Review Order Complete 2 4 Thank You PAY 4 3 peke PayPal Web Semwices 1 On your website the customer chooses to pay with a 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 send the Direct Payment request Within seconds you receive the response confirming that the transaction has been processed 4 You transfer your customer to your order confirmation page The Pay button on your website sends the Direct Payment request over the Payflow gateway to the server The request includes the required information you collected from the customer such as the amount of the transaction the buyer s credit card number expiration date browser IP address and an element that specifies whether the transaction is a final sale or an authorization for a final amount that you capture in a subsequent transaction PayPal is completely invisible to your customer before during and after the purchase PayPal does not send an email receipt to the customer nor does the customer s credit card statement indicate that PayPal processed the payment Direct Payment credit card processing is not covered by the PayPal Seller Protection Policy SPP Website Payments Pr
52. mat For example 1008 represents November 2008 ACCTTYPE Optional Credit card type The following card types are supported e 0 Visa e MasterCard 2 Discover 3 AMEX 8 Other AMT Required Amount US Dollars U S based currency AMT ITEMAMT TAXAMT FREIGHTAMT HANDLINGAMT INSURANCEAMT DISCOUNT NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Must not exceed 10 000 USD in any currency Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal CURRENCY Required The currency code See Appendix B Currency Codes NOTE CURRENCY is applicable only to processors that support transaction level currency Limitations Three characters BUTTONSOURCI Optional Identification code for use by third party applications to identify transactions Limitations 32 alphanumeric characters CUSTIP Optional IP address of payer s browser as recorded in its HTTP request to your website This value is optional but recommended NorE PayPal records this IP address as a means to detect possible fraud Limitations 15 character string in dotted quad format x
53. meters e Parameters specific to the type of the transaction such as a sale or an authorization Data Modes for Sending You can send parameter data in the transaction 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 14 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 XML documents to the Payflow server based on the XMLPay 2 0 schema For details on XMLPay see XMLPay Developer 5 Guide in the Payflow Pro documentation on Developer Central Website Payments Pro Payflow Edition Developer s Guide 13 14 Simple Payflow Transaction Transaction Requests Connection Parameters The connection parameters are described below 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 Parameter HOSTADDRESS HOSTPORT PARMLIST TIMEOUT PROXYADDRESS PROXYPORT PROXYLOGON PROXYPASSWORD Description Required Payflow host name See Host Addresses on page 9 for details on host addresses Required Use port 443 Required List of parameters that specify the payment information for the tr
54. nce the capture is approved you will see the funds in your PayPal account Considerations Regarding Your Website Integration In the design of your 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 shipping information in your system or you may prefer to send the information to PayPal with the transaction and report on it later 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 Website Payments Pro Payflow Edition Developer s Guide 17 BEER Performing Direct Payment Credit Card Transactions Parameters Used in Transactions 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 fulfillment and customer service you may want to connect these systems directly to your Payflow integration for capturing funds issuing refunds or 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 below
55. nd error 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 VERBOSTTY is set to LOW LOW setting causes the server to normalize the transaction result values Normalizing the values limits them to a standardized set of values and simplifies the process of integration 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 Payflow accounts The following values are returned RESULT PNREF RESPMSG AUTHCODE AVSADDR AVSZIP CVV2MATCH IAVS CARDSECURE e MEDIUM All of the values returned for a LOW setting plus the following values NorE 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 normalized RESPTEXT char 17 Text corresponding to the response code returned by the PayPal processor This text is not normalized PROCAVS char 1 AVS response from the PayPal processor
56. o Payflow Edition Developer s Guide Downloading Installing and Activating The Payflow Software Development Kit SDK is set of APIs to allow you to integrate Website Payments Pro Payflow Edition Payflow Pro with your application or website IMPORTANT Full API documentation is included with each SDK Supported Platforms Payflow Pro is available on all major web server platforms in a variety of formats to support your Integration requirements Payflow Pro is available as a NET or Java library or you can build your own API by posting directly to the Payflow servers via HTTPS Preparing the Payflow Client Application Unless you are building your own API and using HTTPS to post to the servers you will need to obtain the Payflow SDK Follow these steps 1 Download the Payflow SDK From the SDKs and Downloads page linked to the Library tab on PayPal Developer Central download the Payflow SDK appropriate for your platform 2 Extract the files to a local directory 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 Payflow Pro while inbound permits the response from PayPal 4 Read the Readme txt file The Readme
57. o Payflow Edition Developer s Guide Responses to Transaction Requests When a transaction finishes the Payflow server returns a response string made up of name value pairs This is an example response string RESULT 0 amp PNREF EFHP0D426A53 amp RESPMSG APPROVED amp AUTHCODE 25TEST amp AVSADDR Y amp AVSZIP N amp CVV2MATCH Y Contents of a Response to a Credit Card Transaction Request The table below describes values that can be returned in response strings TABLE 5 9 Transaction response values Field Description PNREF Payflow Transaction ID a unique number that identifies the transaction Character length and limitations 12 alphanumeric characters PPREF Unique transaction ID of the payment Character length and limitations 17 character string RESULT The outcome of the attempted transaction RESULT 0 means the transaction was approved Any other value for RESULT indicates a decline or error The PayPal processor may also return a warning message in the RESPMSG string when RESULT 0 For more information on corrective actions see the PayPal developer documentation on Developer Central Character length and limitations variable length numeric CVV2MATCH 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 Character length and limitations 1 alpha character Y N X
58. ocessor 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 6 1 Testing credit card numbers Credit Card Number American Express 378282246310005 American Express 371449635398431 Amex Corporate 378734493671000 Australian BankCard 5610591081018250 Diners Club 30569309025904 Diners Club 38520000023237 Discover 6011111111111117 Discover 6011000990139424 JCB 3530111333300000 JCB 3566002020360505 Website Payments Pro Payflow Edition Developer s Guide 51 BE Testing Credit Card Transactions Testing Result Code Responses TABLE 6 1 Testing credit card numbers Credit Card Number MasterCard 5555555555554444 MasterCard 5105105105105100 Visa 4111111111111111 Visa 4012888888881881 Visa 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 The table below lists the general guidelines for specifying amounts TABLE 6 2 Obtaining PayPal result code Result Definition How to test 0 Approved Use an AMOUNT of 10000 or less 3 Invalid transaction type Use the AMOUNT 10402 4 Invalid amount Use any of these as AMOUNT e 10400 e 10401 e 10403 e 10404 5 Invalid merchant information Use any of these as AM
59. on Transactions not settled 206 Transactions on hold pending customer intervention DATE TO SETTLE Date format 19 Value available only before settlement has started YYYY 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 56 Website Payments Pro Payflow Edition Developer s Guide Verbosity Viewing Processor Specific Transaction Results Changing the Verbosity Setting A Table A 2 shows the increments that are possible on basic TRANSSTATE values TABLEA 2 TRANSSTATE increments Increment 100 200 1000 Meaning The TRANSS For transactions in TRANSSTATI TATE is incremented by 100 if no client acknowledgment is received For example if the original TRANSSTATE is 6 the new TRANSSTATE 18 106 Transactions in this range do not settle E 106 use Auto Resettle in PayPal Manager s Transaction Terminal to submit them for settlement or void them using a manual Void The host process never receives ACK from the transaction broker or backend payment server A transaction with a TRANSSTATE incremented by 200 is basically in limbo and will not be settled If a void is run against a successful Authorization or Sale transaction the original TRANSSTAT 6 the new T E is incremented by 1000 For example if the
60. on Processor does not recognize 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 expiration date and transaction information to make sure they were entered correctly If this does not resolve the problem have the customer call their card issuing bank to resolve 13 Referral Transaction cannot be approved electronically but can be approved with a verbal authorization Contact your merchant bank to obtain an authorization and submit a manual Voice Authorization transaction 19 Original transaction ID not found The transaction ID you entered for this transaction is not valid See RESPMSG 20 Cannot find the customer reference number 22 Invalid ABA number Website Payments Pro Payflow Edition Developer s Guide 43 44 Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 50 51 99 100 101 102 103 RESPMSG and Explanation Invalid account number Check credit card number and re submit Invalid expiration date Check and re submit Invalid Host Mapping You are
61. ons Four digits EMAIL Optional Email address of payer Limitations 127 alphanumeric characters INVNUM Optional Your own unique invoice or tracking number Limitations 127 alphanumeric characters ITEMAMT Required if LL COSTn is specified Sum of cost of all items in this order ITEMAMT QTYO LCOSTO L QTY1 LCOST1 L QTYn L COSTn Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point Uuse 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Limitations Nine numeric characters plus decimal TAXAMT Required if L_TAXAMTn is specified Sum of tax for all items in this order TAXAMT L QTYO L TAXAMTO L QTY1 L L L TAXAMIn NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal 20 Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions am Parameters Used in Transactions TABLE 4 1 Credit card transaction request parameters Parameter Description
62. or no response Website Payments Pro Payflow Edition Developer s Guide 37 Responses to Transaction Requests Contents of a Response to a Credit Card Transaction Request TABLE 5 9 Transaction response values Field RESPMSG AUTHCODI AVSADDR AVSZIP IAVS PROCAVS PROCCVV2 Description The response message returned with the transaction result Exact wording varies Sometimes a colon appears after the initial RESPMSG followed by more detailed information NorE The PayPal processor may also return a warning message in the RESPMSG string when RESULT 0 For more information on corrective actions see the PayPal developer documentation on Developer Central Character length and limitations variable alphanumeric characters Returned for Sale Authorization and Voice Authorization credit card transactions AUTHCODE is the approval code obtained over the telephone from the processing network AUTHCODE is required when submitting a Force F transaction Character length and limitations 6 alphanumeric characters Address Verification Service address response returned if you are using Address Verification Service Address Verification Service address responses are for advice only This process does not affect the outcome of the authorization Character length and limitations 1 alpha character Y N X or no response Address Verification Service address response returned if yo
63. original TRANSSTATE is RANSSTATE 15 1006 Changing the Verbosity Setting To specify a setting for V ERBOSITY that differs from your account s current setting include the VERBOSITY value name value pair in the transaction request where value is LOW or MEDIUM This is an example response with no VE RESULT 0 amp PNR I T EF E19P0F5 P Y amp CVV2MATCH Y amp PPRI RESULT 0 amp PNR IP Y amp CVV2MATCH Y amp PPRI S X amp PROCCVV2 M amp IAVS N EF E79POE2 RI BOS ITY defined A5B95 amp RI his is an example response from the same request with VER ESPMSG Approved amp AUTH EF 70C67987W0761540M amp CORRI CODE 111111 amp AVSADDR Y amp AVSZ ELATIONID 23795 89710e7 amp IAVS N BOS I TY MED I UM 3873D amp RESPMSG Approved amp AUTH Website Payments Pro Payflow Edition Developer s Guide EF 71L65308H1608350J amp CORRI CODE 111111 amp AVSADDR Y amp AVSZ ELATIONID 6e4bbbefabd69 amp PROCAV 57 A Verbosity Viewing Processor Specific Transaction Results Changing the Verbosity Setting 58 Website Payments Pro Payflow Edition Developer s Guide The following currencies are supported for use in transactions NorE American Express and Discove Currency Codes ry support USD only TABLE B 1 Currencies and Currency Codes Code AUD CAD EUR JPY GBP USD Currency
64. p PWD SuperUserPassword amp ORIGID EFHPOD4206A68 Website Payments Pro Payflow Edition Developer s Guide 31 32 Performing Direct Payment Credit Card Transactions Recharging to the Same Credit Card Reference Transactions 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 web site store 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 shipping 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 I MPORTANT Asa security measure reference transactions are disallowed by default 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 value 117 is returned See PayPal Manager on
65. parameters STREET and ZIP RXTYPE A amp TENDER C amp PWD password amp PARTNER partner amp VENDOR vendor amp USER user amp ACC T 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 amp STREET 5199 Maple amp ZIP 98765 Example Address Verification Service Response In this example the address value matches the value in the bank s records but the ZIP code does not The 5 response is X RESULT 0 amp PNREF EFHPOD426A56 amp RESPMSG APPROVED amp AVSADDR Y amp AVSZIP N amp IAVS XG amp CORR ELATIONID 2dc60e253496a amp PPREF 68W3371331353001F 34 Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions Card Security Code Validation Card Security Code Validation The card security code is a 3 or 4 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 This fraud prevention tool has various names depending on the payment network Visa calls it CVV2 and 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 CV V2 value as a transaction parameter for those credit cards
66. phanumeric characters Optional Bill to state or province address Limitations 40 alphanumeric characters Optional Bill to country address Limitations 2 alphanumeric characters Optional Bill to postal code Limitations Nine characters maximum Do not use spaces dashes or non numeric characters 22 Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions Submitting Sale Transactions TABLE 4 1 Credit card transaction request parameters Parameter SHIPTOSTREE SHIPTOCITY SHIPTOSTATI SHIPTOCOUNTRY SHIPTOZIP Description Optional Ship to street address NOTE If you pass in any of the ship to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that is SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Limitations 30 character string Optional Ship to city address NOTE If you pass in any of the ship to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that is SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY and SHIPTOZIP Limitations 40 character string Optional Ship to state or province address NOTE If you pass in any of the ship to address parameters such as SHIPTOCITY or SHIPTOSTATE you must pass in the complete set that is SHIPTOSTREET SHIPTOCITY SHI
67. pro paypal com 9 PNREF Website Payments Pro Payflow Edition Developer s Guide format of value 41 PNREF value 41 Polish Zloty 59 Pound Sterling 59 PROCAVS parameter 55 PROCCARDSECURE parameter 55 PROCCV V2 parameter 55 PWD parameter 15 R Real 59 RECURRINGTYPEparameter 22 reference transactions when to use 32 RESPMSG value 42 RESPTEXT parameter 55 RESULT value 42 Ringgit 59 S sale transaction type 23 sale transactions when to use 23 Sample Code and Documentation 7 SETTLE DATE parameter 56 SHIP TO Address parameters 23 SHIPTOCITY parameter 23 SHIPTOCOUNTRYparameter 23 SHIPTOSTATEparameter 23 SHIPTOSTREET parameter 23 SHIPTOZIP parameter 23 Singapore Dollar 59 SSL 11 STATE parameter 22 storefront testing 51 storing credit card numbers 17 STREET parameter 22 Swedish Krona 59 Swiss Franc 59 T Taiwan New Dollar 59 TAXAMTparameter 20 TENDER parameter 18 testing operation 51 69 70 testing transactions host address 9 Thai Baht 60 transaction response PNREF parameter 41 RESPMSG parameter 42 RESULT parameter 42 transactions credit 28 sale 23 void 30 TRANSSTATE 106 57 TRANSSTATE parameter 56 TRXTYPE parameter 18 type N transactions 18 U U S Dollar 60 USER parameter 15 using Authorization Delayed Capture transactions 24 using Delayed Capture transactions 27 V VENDOR parameter 15 VERBOSITY changing setting 57 settings 55 VERBOSITY parameter 20 55 void transaction type 30 void
68. rization Delayed Capture Transactions association rules recommend that you use an Authorization and a Delayed Capture transaction For details see Submitting Authorization Delayed Capture Transactions on page 24 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 32 Additional Parameters For Sale Transactions To perform a Sale transaction you are required to pass the following parameters e ACCT e AMT e Typical Sale Transaction Parameter String The following is a typical PARMLIST string passed in a Sale transaction TRXTYPE S amp TENDER C amp USER user amp PWD password amp PARTNER partner amp ACCT 510510510510 5100 amp EXPDATE 1209 amp AMT 99 06 amp COMMENT1 Reservation amp FIRSTNAME John amp LASTNAME JO nes amp STREET 123 Main St amp CITY San Jose amp STATE CA amp ZIP 123451234 amp COUNTRY US amp CVV2 123 amp CUSTIP 0 0 0 0 Note that besides the required parameters that you pass in a Sale transaction this string includes other typical parameters PayPal recommends that you include the account holder s FIRSTNAME and LASTNAME PayPal also recommends including CUSTIP to help detect possible fraud The COMMENT1 fie
69. s for Higher Amounts You can perform a Delayed Cap ture transaction for an amount higher than the original Authorization amount cardholder s open to buy could be reduced by the sum of the original Authorization only amount and the final Delayed Capture amount Delayed Capture Transaction Error Handling and Retransmittal If an error occurs while processing a Delayed Capture transaction it is safe to retry the capture with values that allow the Payflow server to successfully process it Conversely if a capture for a previous Authorization succeeds subsequent attempts to capture it again will return an error Submitting Credit Transactions The Credit transaction TRXT YP Required Credit Transaction Pa The required parameter data for credits security setting for your transaction that does not use the E C refunds the specified amount to the cardholder rameters a Credit transaction depends on the Allow non referenced Payflow Pro account A non referenced credit is a Credit credit card information from an existing transaction Credit card information must be supplied As an example Sally Smith calls you on the telephone to Website Payments Pro Payflow Edition Developer s Guide Performing Direct Payment Credit Card Transactions Submitting Credit Transactions cancel an order from your business To refund her money you credit her credit card by submitting a non referenced Credit transaction Guidel
70. security setting for Payflow Pro accounts is Allow non referenced credits No so sending the ORIGID is the preferred method for performing Credit transactions Using the ACCT EXPDATE or AMT parameters for such accounts leads to RESULT value 117 failed the security check For information on setting the security settings see PayPal Manager online help 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 EXPDATE and SWIPE These parameters retain their original values Website Payments Pro Payflow Edition Developer s Guide 29 30 Performing Direct Payment Credit Card Transactions Submitting Void Transactions Note TAXAMT and FREIGHTAMT not copied for referenced credits TABLE 4 5 Fields copied from original transaction into the Credit transaction ACCT AMT CITY COMMENT 1 COMMENT2 COUNTRY CUSTCODE CUSTIP EMAIL EXPDATE FIRSTNAME INVNUM ASTNAME PHONEU SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET ZIP Credit Transaction Parameter Strings This is an example Credit transact
71. st 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 120 Attempt to reference a failed transaction 121 Not enabled for feature Website Payments Pro Payflow Edition Developer s Guide 45 46 Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT 122 125 126 127 128 132 133 150 151 200 201 600 601 1000 1001 1002 1003 1004 1011 1012 RESPMSG and Explanation Merchant sale total will exceed the credit cap with current transaction ACH transactions only Fraud Protection Services Filter Declined by filters Fraud Protection Services Filter Flagged for review by filters I MPORTANT RESULT value 126 indicates that a transaction triggered a fraud filter This is not an error but a notice that the transaction is in a review status
72. t CAPTURECOMPLETE to N in the Delayed Capture transaction request Setting CAPTURECOMPLETE to Y voids any remaining amount of the original authorized transaction You can also perform Authorizations and Delayed Captures through through PayPal Manager For details see PayPal Manager online help Example Partial Capture Transaction In this example you authorize an amount of 100 for a shipment and charge 66 for the first partial shipment using a Delayed Capture transaction You charge the 34 for the final part of the shipment using a second Delayed Capture transaction to draw credit card and shipping address information from the initial Authorization transaction 1 Submit the initial transaction Authorization in this example This example uses an Authorization transaction for the full amount of a purchase of 100 IRXTYPE A amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPal amp VENDOR SuperMerc hant amp USER SuperMerchant amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 100 00 amp IN VNUM 123456789 amp FIRSTNAME John amp LASTNAME Jones amp STREET 5199 MAPLE amp ZIP 94588 Note the value of the PNREF in the response RESULT 0 amp PNREF EFHPOD426A51 amp RESPMSG Approved amp AVSADDR N amp AVSZIP Y amp CVV2MATC H X amp PPREF 6FS950632E172331R amp CORRELATIONID 3c1a7c1c411a I Website Payments Pro Payflow Edition Developer s Guide 27
73. t a standalone feature You must use Direct Payment together with Express Checkout Use this guide along with the companion guide Express Checkout for Payflow Pro for details on integrating Express Checkout About Direct Payment Credit Card Processing Direct Payment credit card processing occurs in two steps a real time authorization and a capture settlement of the funds that were authorized You perform these two steps either as a single Sale transaction or as two types of transactions an Authorization and Delayed Capture depending on your business model For an Authorization 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 34 e Card Security Code Validation on page 35 You receive the response shortly after you submit the transaction to PayPal If the Authorization is approved the bank temporarily reserves credit for the amount of the transaction to prepare to capture fulfill 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 O
74. that use card security code validation The value is required for Visa and MasterCard cards I MPORTANT To comply with credit card association regulations do not store the CVV2 value 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 American Express the 4 digit number 1122 in the example is printed on the front of the card above and to the right of the embossed account number Be sure to explain this to your customers For details on PayPal processor card security code responses see Responses to Transaction Requests on page 37 FIGURE 4 1 Card security code Example CVV2 Request This example request parameter string includes the CVV2 parameter TRXTYPE A amp TENDER C amp PWD SuperUserPassword amp PARTNER PayPal amp VENDOR SuperMerchan t amp USER SuperMerchant amp ACCT 5555555555554444 amp EXPDATE 0308 amp AMT 123 00 amp CVV2 56 70 Example CVV2 Response In this example result the card security code value matches the value in the bank s records Website Payments Pro Payflow Edition Developer s Guide 35 Performing Direct Payment Credit Card Transactions Card Security Code Validation RESULT 0 amp PNREF VXW412345678 amp RESPMSG APPROVED amp CVV2MATCH Y amp PPREF 68W33713313 53001F amp CORRELATIONID 2dc60e2534971 amp PPREF 68W3371331353001F 36 Website Payments Pr
75. u are using Address Verification Service Address Verification Service address responses are for advice only This process does not affect the outcome of the authorization Character length and limitations 1 alpha character Y N X or no response International Address Verification Service address responses may be returned if you are using Address Verification Service IAVS responses are for advice only This value does not affect the outcome of the transaction Indicates whether Address Verification Service response is international Y US N or cannot be determined X Client version 3 06 or later is required Character length and limitations 1 alpha character Y N X or no response Address Verification Service response from the processor when you use Address Verification Service and send a VERBOSITY request parameter value of MEDIUM Character length and limitations I character CVV2 response from the processor when you send a VERBOSITY request parameter value of MEDIUM Character length and limitations 1 character 38 Website Payments Pro Payflow Edition Developer s Guide Responses to Transaction Requests BT Address Verification Service Responses From PayPal TABLE 5 9 Transaction response values Field Description PAYMENTTYPE Returns instant if the payment is instant or echeck if the payment is delayed DP Character length and limitations 7 character string CORRELATIONID V
76. verage of PayPal success with warning message which can be returned by PayPal when RESULT O Added support for non referenced credits Updated test and live host URLs Explains how merchant can determine what SDK version they are using Explains more about VERBOSITY parameter Explains how to eliminate TRANSSTATE 106 results Updates Index to include an alphabetical listing of all Payflow parameters cited in the guide Updated Figures 1 1 and 4 1 to show new PayPal logo Adds new transaction type N Includes other minor edits for technical accuracy Website Payments Pro Payflow Edition Developer s Guide Introduction This chapter introduces the Website Payments Pro Payflow Edition product and provides an overview of its Direct Payment credit card processing payment solution About Website Payments Pro Payflow Edition Website Payments Pro Payflow Edition uses the Payflow gateway and Payflow Pro SDK to send transactions to PayPal for processing It is available from the PayPal Manager Downloads page as a NET or Java library or you can build your own API by posting directly to the servers via HTTPS With Website Payments Pro Payflow Edition you get the payment processing capabilities of a merchant account and gateway plus much more It is an all in one payment solution that includes e Express Checkout which allows PayPal account holders to check out fast with saved information and enables you to g
77. website for information on corrective actions 42 Website Payments Pro Payflow Edition Developer s Guide Responses to Transaction Requests RESULT Values and RESPMSG Text TABLE 5 13 Payflow Transaction RESULT Values and RESPMSG Text RESULT RESPMSG and Explanation 1 User authentication failed Error is caused by one or more of the following e Login information is incorrect Verify that USER VENDOR PARTNER and PASSWORD have been entered correctly VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user All fields are case sensitive e Invalid Processor information entered Contact merchant bank to verify e Allowed IP Address security feature implemented The transaction is coming from an unknown IP address See PayPal Manager online help for details on how to use Manager to update the allowed IP addresses e You are using a test not active account to submit a transaction to the live PayPal servers Change the host address from the test server URL to the live server URL 2 Invalid tender type Your merchant bank account does not support the following credit card type that was submitted 3 Invalid transaction type Transaction type is not appropriate for this transaction For example you cannot credit an authorization only transaction 4 Invalid amount format Use the format HP Do not include currency symbols or commas 5 Invalid merchant informati
78. xx xxx xxx xxx COMMENT 1 Optional Merchant defined value for reporting and auditing purposes Limitations 128 alphanumeric characters Website Payments Pro Payflow Edition Developer s Guide 19 BEER Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4 1 Credit card transaction request parameters Parameter Description COMMENT2 Optional Merchant defined value for reporting and auditing purposes Limitations 128 alphanumeric characters CAPTURECOMPLETE Optional Indicates if this Delayed Capture transaction is the last capture you intend to make The values are e Y default eN NOTE If CAPTURECOMPLETE is Y any remaining amount of the original reauthorized transaction is automatically voided Limitations 12 character alphanumeric string CUSTO Optional A free form field for your own use Limitations 256 character alphanumeric string CUSTREF Optional Merchant defined identifier for reporting and auditing purposes For example you can set CUSTREF to INVNUM Limitations 12 alphanumeric characters CVV2 Optional A code that is printed not imprinted on the back of a credit card and used as partial assurance that the card is in the buyer s possession NOTE CVV2 values are normalized to Y N and X values The PayPal processor values are returned when you set VERBOSITY parameter to MEDIUM Limitati
79. y the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 _ NAMEN Optional Line item name Character length and limitations 36 alphanumeric characters DESCn Optional Line item description of the item purchased such as hiking boots or cooking utensils Limitations 127 alphanumeric characters L COSTn Required if L OTYn is supplied Cost of the line item The line item unit price can be a positive or a negative value but not 0 NOTE You must set CURRENCY to one of the three character currency codes for any of the supported PayPal currencies See CURRENCY in this table for details Limitations Nine numeric characers plus decimal character No currency symbol Specify the exact amount to the cent using a decimal point use 34 00 not 34 Do not include comma separators use 1199 95 not 1 199 95 Nine numeric characters plus decimal L OTYn Required if L COSTn is supplied Line item quantity Limitations 10 character integer Website Payments Pro Payflow Edition Developer s Guide 21 BEER Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4 1 Credit card transaction request parameters Parameter L SKUn L TAXAMTn MERCHANTSESSIONID NOTIFYURL RECURRINGTYPE FIRSTNAME LASTNAME STREET CITY

PayPal Website Payments Pro - 2009 Payflow Edition Developer's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents