Home

PayPal Pro - 2012 Integration Guide

Contents

1. NVP SOAP Description L _PAYMENTREQUEST_0_ ItemCategory For digital goods this field must be set to ITEMCATEGORYN Digital e Digital e Physical L_PAYMENTREQUEST_0_ Name Ttem name NAMEN PAYMENTREQUEST_O_ Amount Cost of item AMTn PAYMENTREQUEST_O_ Quantity Item quantity OTYN Recurring Payments Profile Status The recurring payments actions you may take depend on the status of the profile A recurring payments profile can have one of the following status values e ActiveProfile e PendingProfile e ExpiredProfile e SuspendedProfile e CancelledProfile If PayPal successfully creates the profile the profile has an ActiveProfile status However if a non recurring initial payment fails and you set FAILEDINITAMTACTION to PayPal Payments Pro Integration Guide April 2012 69 70 Integrating Recurring Payments Getting Recurring Payments Profile Information CancelOnFailure in the CreateRecurringPaymentsProfile request PayPal creates the profile with a status of PendingProf ile The profile remains in this status until the initial payment either completes successfully or fails A profile has a status of ExpiredProfile when PayPal completes the total billing cycles for the optional trial and the regular payment periods You can suspend or cancel a profile by using the ManageRecurringPaymentsProfileStatus API You can also reactivate a suspended profile If PayPal has al
2. 1 Calls SetExpressCheckout setting up one or more billing agreements in the request Redirects buyer s browser to https www paypal com cgi bin webscr cmd _express checkout amp token lt token returned by SetExpressCheckout gt Calls GetExpressCheckoutDetails to get buyer information optional Displays merchant review page for buyer Calls DoExpressCheckoutPayment if the order includes one time purchases as well as a recurring payment Otherwise skip this step Calls CreateRecurringPayment sProfile one time for each recurring payment item included in the order Displays successful transaction page Returns a token which identifies the transaction to the merchant Displays login page and allows buyer to select payment options and shipping address Redirects buyer s browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description Returns GetExpressCheckoutDetails response Returns Do ExpressCheckoutPayment response Returns ProfileID in CreateRecurringPayment sProfile response for each profile successfully created Initiating the Processing Flow With SetExpressCheckout PayPal Payments Pro Integration Guide As in the Express Checkout flow the SetExpressCheckout request notifies PayPal that you are e Initiating an order that can be either a one time purchase up to 10 recurring payments or a mixture of a one time purchase and rec
3. 2009 a DoDirectPayment request returns ACK SuccessWithWarning with error code 12001 PayPal still accepts the transaction e Beginning on 1 January 2010 a DoDirectPayment request will return ACK Failure with error code 12000 and PayPal will not accept the transaction Testing For 3 D Secure you cannot use PayPal s sandbox for testing You must use Cardinal s test procedures Refer to the Cardinal documentation PayPal Payments Pro Integration Guide April 2012 95 96 Implementing 3 D Secure Transactions UK Only cmpi_lookup API cmpi_lookup API The cmpi_lookup request is a Cardinal Centinel request This section lists required fields and responses as a convenience for you Refer to the Cardinal Thin Client Integration Guide Payer Authentication document for details and the most current information cmpi_lookup Request cmpi_lookup Request Fields Field sgType Version Processorld erchant Id TransactionPwd TransactionType Amount CurrencyCode CardNumber CardExpMonth CardExpYear OrderNumber various additional fields Description Required Must be cmpi_lookup Required Must be 1 7 Required Your processor identification code assigned by Cardinal when you register Required Your merchant identification code as assigned by Cardinal Required Your Cardinal password as you configured it at the Cardinal Site Required Must be C Required The value of th
4. IMPORTANT PayPal does not create the recurring payments profile until you receive a success response from the CreateRecurringPaymentsProfile call To obtain the best rates for digital goods set values for the following required payment details item fields e TI PAYMENTREQUEST_O_NAMEN e TI PAYMENTREQUEST_0_AMTn e TI PAYMENTREQUEST_0_QOTYn e Il PAYMENTREQUEST_0O_ITEMCATEGORYn you must set the value to Digital PayPal Payments Pro Integration Guide April 2012 65 6 Integrating Recurring Payments Options for Creating a Recurring Payments Profile NOTE The payment details item fields are available with version 69 0 and later of the CreateRecurringPaymentsProfile API The CreateRecurringPaymentsProf1ile response contains a Profile ID which is an encoded string that uniquely identifies the recurring payments profile The following is a Creat eRecurringPayment sProfile example that enables you to obtain the best rates for digital goods items Request Parameters requiredSecurityParameters amp METHOD CreateRecurringPaymentsProfile TOKEN EC 13W99099UU817504D amp PROFILESTARTDATE 20XX 03 05T03 00 00 amp DESC Movie clips amp BILLINGPERIOD Month amp BILLINGFREQUENCY 12 amp AMT 1 00 amp CURRENCY CODE USD amp EMATL payername bbb net amp L_PAYMENTREQUEST_0O_ITEMCATEGORY0 Digital amp L_PAYMENTREQUEST_O_NAME0O Kitty Antics L PAYMENTREQUEST_0_AMTO0 1 00 KL PAYMENTREQUES
5. iia a a A a ee a a 95 cmpi_lookup API oea a a o 96 cmpi_lookup Request 2 e 96 cmpi_lookup Response 00 ee ee 96 Issuer Authentication Fields 2 2 e e 97 Issuer Authentication Request a aoao a a a eo 97 Issuer Authentication Response aoa oaa aa a eo 98 cmpi_authenticate API a 98 cmpi_authenticate Request 0 00002 eee eee ee 98 cmpi_authenticate Response 0 o 98 6 April 2012 PayPal Payments Pro Integration Guide Preface This document describes PayPal Payments Pro known as Website Payments Pro outside the U S integration Intended Audience This document is intended for merchants and developers implementing PayPal Payments Pro Revision History Revision history for PayPal Payments Pro Integration Guide Date Description 04 03 12 Updated references to Website Payments Standard and Website Payments Pro to PayPal Payments Standard and PayPal Payments Pro respectively 02 13 12 Updated user experience graphics 12 20 10 Replaced deprecated field names in examples 10 26 10 Added a reference to information on Mobile Express Checkout which is located in the Epxress Checkout Integration Guide 08 11 10 Divided the Website Payments Pro Integration Guide into 2 guides the Website Payments Pro Integration Guide and the Express Checkout Advanced Features Guide 05 11 10 Added details for integrating parallel payments u
6. regardless of the currency used AMT amount CURRENCY CODE currencyID 2 Specify the payment action Although the default payment action is a Sale it is a best practice to explicitly specify the payment action as one of the following values PAYMENTACTION Sale PAYMENTACTION Authorization 3 Specify the IP address of the buyer s computer IPADDRESS 192 168 0 1 PayPal Payments Pro Integration Guide April 2012 33 34 Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL 4 Specify information about the credit or debit card You must specify the kind of credit or debit card and the account number CREDITCARDTYPE Visa ACCT 4683075410516684 NOTE The kind of card the card issuer and Payment Receiving Preferences settings in your PayPal profile may require you set additional fields EXPDATE 042011 CVV2 123 note UK merchants must also specify values for 3D Secure related fields when using Maestro 5 Specify information about the card holder You must specify the first and last name and the billing address associated with the card FIRSTNAME LASTNAME STREET CITY STATE ZIPS s COUNTRYCODE NOTE The state and zip code is not required for all countries Testing Direct Payment Using NVP and cURL To test direct payment you must first create a test business account in the Sandbox that is enabled for PayPal Pay
7. Both periods contain information about the payment frequency and payment amounts including shipping and tax if applicable After creating a profile PayPal automatically queues payments based on the billing start date billing frequency and billing amount Payments reoccur until the profile expires there are too many failed payments to continue or you cancel the profile NOTE When using Express Checkout the buyer can also cancel a recurring payments profile PayPal funds queued payments using the normal payment method hierarchy within the buyer s PayPal account After creating a recurring payments profile you can view profile details or cancel the profile from your PayPal account You can also access recurring payments reports from the PayPal Business Overview page Also after creating a recurring payments profile you can use the Recurring Payments API to do the following PayPal Payments Pro Integration Guide April 2012 59 E Integrating Recurring Payments Recurring Payments Terms e Get information details about a recurring payments profile e Change the status of a recurring payments profile e Update the details of the recurring payments profile e Bill the outstanding amount of the recurring payments profile Limitations The current release of the Recurring Payments API has the following limitations e A profile can have at most one optional trial period and a single regular payment period e The profile start d
8. DoCapture request to specify the authorization that you want to capture April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment Direct Payment Authorization and Captures lt form method post action https sandbox paypal com nvp gt lt input type hidden name USER value gt lt input type hidden name PWD value gt lt input type hidden name SIGNATURE value gt lt input type hidden name VERSION value 58 0 gt lt input type hidden name AUTHORIZATIONID value 6RH38738S17889722 gt lt input type hidden name AMT value 5 gt lt input type hidden name CURRENCYCODE value USD gt lt input type hidden name COMPLETETYPE value Complete gt lt input type hidden name INVNUM value gt lt input type hidden name NOTE value March 08 2010 gt lt input type hidden name SOFTDESCRIPTOR value gt lt input type submit name METHOD value DoCapture gt lt form gt If the capture was successful the payment status is Completed AUTHORIZATIONID 6RH38738S17889722 amp TIMESTAMP 2010 2d03 2d08T1 9 3a47 3a39Z amp CO RRELATIONID d1e8043ae0al12 amp ACK Success amp VERS ION 58 2e0 amp BUILD 1218643 amp TRANSACT TONID 5F62121256435650V amp 83202 642 2d6061 2d5728 amp T EDECHI ECKCLI EARDATI 3a47 3a38Z8AMT 5 2e008 FE TATUS Completede eligible PARENTTRANSACTIONID 6RH387
9. Make a payment to one or more PayPal account holders NOTE If you use the Payflow API to process transactions with PayPal as your internet merchant account see Gateway Developer Guide and Reference 14 April 2012 PayPal Payments Pro Integration Guide Introducing PayPal Payments Pro E Website Payments Pro Regional Differences Website Payments Pro Regional Differences Website Payments Pro is available in the United States Canada and the United Kingdom Minor regional differences include transaction limits the kinds of credit cards accepted and address information The following sections identify regional differences Credit Cards The following table lists the credit cards that are accepted Country Accepted credit cards Canada e Visa e MasterCard NOTE Interac debit cards are not accepted United Kingdom Visa including Visa Electron and Visa Debit MasterCard e Maestro including Switch United States Visa MasterCard Discover American Express MasterCard is a registered trademark NOTE For direct payment only American Express restricts direct card acceptance merchants in certain business categories Merchants are required to accept the American Express Card Acceptance agreement in order to process American Express cards directly Default Currency and Transaction Limits The following table lists the default transaction limit in the default currency for each country Country D
10. Specifying the Regular Payment Period o 66 Including an Optional Trial Period 2 2 o e 67 Specifying an Initial Payment e e 68 Maximum Number of Failed Payments 0000000 68 Billing the Outstanding Amount 2 2 0 ee 69 Identifying Items as Digital or PhysicalGoods 004 4 69 Recurring Payments Profile Status 2 ee 69 Getting Recurring Payments Profile Information 2 002 000 0 0G 70 Modifying a Recurring Payments Profile 2 000 e 70 Updating Addresses a 71 Updating the Billing Amount o o o 71 Billing the Outstanding Amount of a Profile 0 0 0 0 02 ee 72 Recurring Payments Notifications 0 o e ee 72 Appendix A Getting Started With the PayPal Name Value Pair API 75 PayPal API Client Server Architecture 2 2 o 75 PayPal Name Value Pair API Requests and Responses 76 UTF 8 Character Encoding 2 0 00 0 e 76 Multiple API Operations aoa aa ee 76 Obtaining API Credentials 2 o 77 Creating an API Signature o o e mo 78 Creating an API Certificate ee 79 NVP Format cis a Ra a A Se a A 80 Creating an NVP Request aoaaa aa a 80 Specifying the PayPal API Operation oaoa
11. UCS Transformation Format 8 bit encoding form UTF 8 In responses the API always returns data in UTF 8 Multiple API Operations Some of the features such as Express Checkout require you to call multiple API operations Typically these features require you to 76 April 2012 PayPal Payments Pro Integration Guide Getting Started With the PayPal Name Value Pair API Obtaining API Credentials 1 Invoke an API operation such as SetExpressCheckout that sets up the return URL to which PayPal redirects your buyer s browser after the buyer finishes on PayPal Other setup actions also can be performed by this API operation 2 Invoke additional API operations after receiving the buyer s permission on PayPal for example GetExpressCheckoutDetails or DoExpressCheckoutPayment The following diagram shows the execution flow between your site and PayPal cc O Checkout mn Request r I ABs _ _ _ _ Response re API Server ri A L Redirect to PayPal ue hopin a 11 y rB PayPal Redirects ME Continue T S A Receipt ees ROCS PayPal Pay Now D A Response m API Server Token Usage Typically the API operation that sets up a redirection to PayPal returns a token This token is passed as a parameter in the redirect to PayPal The token also might be required in related API operations Obtaining API Credentials To use the PayPal API you must have API credentials that identify you as a PayPal Business
12. a ee eae 80 Specifying an API Credential e o 81 URL ENCOJING gt ear doa SOR RE e A De dr RR a Ea 82 List Syntax for Name Value Pairs 2 2 a 83 Executing NVP API Operations e e 84 Specifying a PayPal Server e 84 Logging API Operations 84 Responding to an NVP Response 0 000 2 eee ee ee eee 85 Common Response Fields e 85 Error Responses a 85 PayPal Payments Pro Integration Guide April 2012 5 EN Contents URE DeCOdING sos ici a a eR ee ae 86 Appendix B Implementing 3 D Secure Transactions UK Only 87 Introduction to 3 D Secure ee 87 Integration Overview aooaa ea e a 88 Cardinal Commerce Registration and Installation a oaoa aa a a 88 Transaction Processing ee 89 URL to Handle Issuer s Response a a 90 Transaction Flow s sa a soca aawa oaa e a a a a a a a a RRR 90 3 D Secure Fields for Direct Payment Transaction Requests 92 Website Setup 2 6 a a a 93 Exainpless 23 2 ge hed haw dh ode Gare ete AAA 94 Example 1 Successful 3 D Secure Authentication 05 94 Example 2 3 D Secure with Unsuccessful Authentication 94 Example 3 Card Issuer Not Using 3 D Secure 204 95 Example 4 Merchant Not Using 3 D Secure 95 TESTO
13. agreement for example L_BILLINGAGREEMENTDESCRIPTIONO Time Magazine subscription 3 If there is no associated purchase set PAYMENTREQUEST_0_AMT to 0 PAYMENTREQUEST_0_AMT 0 4 Optional Set MAXAMT to the average expected transaction amount PayPal uses the value you pass to validate the buyer s payment method for recurring payments If you do not specify a value the default is 25 00 The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls Redirecting the Buyer to PayPal After you receive a successful response from SetExpressCheckout add the TOKEN from the SetExpressCheckout response as a name Vvalue pair to the following URL and redirect your buyer to it https www paypal com cgi bin webscr cmd _express checkout amp token lt value_returned_by_SetExpressCheckoutResponse gt April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments CEN Recurring Payments With the Express Checkout API When redirecting the buyer to PayPal PayPal recommends that you use the HTTPS response 302 Object Moved with the URL as the value of the Location header in the HTTPS response Make sure that you use an SSL enabled server to prevent browser warnings about a mix of secure and insecure graphics Getting Buyer Details Using GetExpre
14. all of the following are true 94 ErrorNo is 0 Enrolledis Y ACSUrl has content for example lt ACSUrl gt https www somewebsite com acs lt ACSUrl gt April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only CS Testing 3 Using HTTP Form POST redirect the cardholder to the issuer s URL that was provided in ACSUr1 Ensure that the PaReq has the data from the field PayLoad from the cmpi_lookup response 4 Send the response redirect from the issuer s HTTP Form POST to Cardinal using the cmpi_authenticate message to determine how to proceed with the transaction 5 The cmpi_authenticate response determines how to proceed In this example when authentication fails the following are true SignatureVerification Y PAResStatus N 6 Notify the cardholder that the transaction is declined Example 3 Card Issuer Not Using 3 D Secure In this example the card s issuer does not use 3 D Secure 1 Construct message for cmpi_lookup 2 Review the response from cmpi_lookup Ensure that ErrorNo 0 Enrolled N or U 3 Authoress as normal with the additional fields described in 3 D Secure Fields for Direct Payment Transaction Requests Example 4 Merchant Not Using 3 D Secure In this example the merchant does not authenticate a Maestro transaction using 3 D Secure before executing a direct payment transaction request e Through 31 December
15. complete list of required fields 5 The cmpi_authent icate request returns several fields Error information Evaluate and take appropriate action if nonzero Refer to the Thin Client Integration Guide for error codes descriptions explanations and recommended actions Authentication information in PAResStatus SignatureVerification Cavv EciFlag and Xid See cmpi_authenticate API for details about the returned fields Evaluate SignatureVerification Ifthe signature is not verified return an authentication failed message to the cardholder and stop processing the transaction If the signature is verified continue with the next section PayPal Payments Pro Integration Guide April 2012 91 B Implementing 3 D Secure Transactions UK Only Transaction Processing 3 D Secure Fields for Direct Payment Transaction Requests If the cardholder is authenticated or if not authenticated for valid reasons such as the authentication service being unavailable or the cardholder not being enrolled execute the direct payment transaction request with the following additional fields NVP SOAP Field SOAP Field Description VERSION Version Set to 59 0 You must use this version number or the request will not work AUTHSTATUS3DS AuthStatus3ds Set this to the returned PAResStatus value IP IVENDOR3DS biVendor3ds Set to the Enrolled value from Step 2 CAVV Cavv Set to the returned Cavv value ECI3DS Eci3ds
16. e On your Payment methods page associate the PayPal mark with an option Handle clicks by sending the Express Checkout setup request After receiving the response redirect your buyer s browser to PayPal e On the page your buyer returns to obtain shipping information from PayPal and accept the payment to complete the Express Checkout transaction NOTE You also can allow the buyer to pay on the PayPal Review your information page In this case your checkout flow can omit your Confirm order page and proceed directly to your Order confirmation page Checkout Entry Point The checkout entry point is one of the places where you must implement Express Checkout Buyers initiate the Express Checkout flow on your shopping cart page by clicking the Checkout with PayPal button The following diagram shows how Express Checkout integrates with a typical checkout flow 26 April 2012 PayPal Payments Pro Integration Guide Introducing Express Checkout PU Express Checkout Building Blocks _ _____ 1s SL gt Conan a a Choose a way Review your to pay information checkout h n lmm sos A a Chockost Confirmation Add To Cart b Ei Pay Now b tas Collect shipping a Confirm order Order eine address PayPal VISA Eo confirmation Shopping cart Payment methods Payment Option Entry Point The payment option entry point is one of the places where you must implement Express Checkout Buyers initiate the Express Checkout flow on your p
17. for each billing cycle The regular payment period begins after the trial period if you specify a trial period for the profile 60 April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments EN Recurring Payments With Direct Payment Term Definition Trial period An optional subscription period before the regular payment period begins A trial period may not have the same billing cycles and payment amounts as the regular payment period Payment amount The amount the buyer pays for each billing cycle Outstanding balance If a payment fails for any reason PayPal adds that amount to the profile s outstanding balance Profile ID An alphanumeric string generated by PayPal that uniquely identifies a recurring profile You can specify the Profile ID in the TransactionSearch API operation to obtain all payments associated with the identified profile Recurring Payments With Direct Payment Recurring payments with Direct Payment enables a recurring payment to be associated with a debit or credit card For these payments you must collect on your website all necessary information from your buyer including billing amount and buyer s credit card information After you have collected the information call the CreateRecurringPaymentsProfile API for each profile to be created The CreateRecurringPaymentsProfile request must contain all required credit card information and must not contain a value for the TO
18. gt lt input type hidden name SIGNATURE value gt lt input type hidden name VERSION value 58 0 gt lt input type hidden name PAYMENTACTION value Authorization gt lt input type hidden name CREDITCARDTYPE value Visa gt lt input type hidden name ACCT value gt lt input type hidden name STARTDATE value 112000 gt lt input type hidden name EXPDATE value 112020 gt lt input type hidden name CVV2 value 123 gt lt input type hidden name AMT value 20 00 gt lt input type hidden name CURRENCYCODE value USD gt lt input type hidden name FIRSTNAME value gt lt input type hidden name LASTNAME value gt lt input type hidden name STREET value gt lt input type hidden name STREET2 value gt lt input type hidden name CITY value San Francisco gt lt input type hidden name STATE value CA gt lt input type hidden name Zip value 94121 gt lt input type hidden name COUNTRYCODE value US gt lt input type hidden name EMAIL value gt lt input type submit name METHOD value DoDirectPayment gt lt form gt If the authorization was successful the response contains the authorization ID in the transaction ID field TIM ESTAI SS amp VI MATCH M amp TRANSACTIONID 6RH38738S17889722 P 2010 2q03 2qd08T19 3a35 3a18Z amp CORRELATIONID ab12f37f9566 amp ACK Succe ERSION 58 2e0 amp BUILD 1218643 amp AMT 20 2e00 amp CURRENCYCODE USD amp AVSCODE X amp CVV2 Use this ID in the
19. include other checkout steps including upselling on your Confirm order page 4 Confirms the order and pays from your site 5 Receives an order confirmation Express Checkout Integration Steps You can implement Express Checkout in 4 steps 1 Place PayPal checkout buttons and PayPal payment mark images in your checkout flow 2 For each PayPal button that you place modify your page to handle the button click Use a PayPal Express Checkout API operation to set up the interaction with PayPal and redirect the browser to PayPal to initiate buyer approval for the payment 3 On your Confirm order page use PayPal Express Checkout API operations to obtain the shipping address and accept the payment 4 Test your integration using the PayPal Sandbox before taking your pages live Because PayPal offers you the flexibility to control your checkout flow you should first understand how your current checkout flow works then become familiar with the Express Checkout flow Start by reviewing Express Checkout Flow For additional background information to help you get started see Express Checkout Building Blocks 24 April 2012 PayPal Payments Pro Integration Guide Introducing Express Checkout E Express Checkout Integration Steps Configuring and Customizing the Express Checkout Experience After you implement and test your basic Express Checkout integration you should configure the additional features of Express Checkout to customize it to
20. meet your needs Carefully evaluate each feature because the more you streamline the checkout process and make Express Checkout seamless to buyers the more likely your sales will increase At a minimum you should e Set your logo on the PayPal site and provide order details in the transaction history e Use the PayPal Review your information page as your Confirm order page to further streamline the user experience when you do not need the benefits associated with paying on your site This strategy can lead to a better order completion rate also known as a conversion rate Configure the look and feel of PayPal pages to match the look and feel of your site by specifying the e Logo to display e Gradient fill color of the border around the cart review area e Language in which PayPal content is displayed You should include e Order details including shipping and tax during checkout IMPORTANT Not displaying this information is a major cause of shopping cart abandonment during checkout e Shipping information for non digital goods which can be your address information for the buyer or the address on file with PayPal if you use the address on file with PayPal you can specify whether or not it must be a confirmed address You can also activate additional features including e Associate a payment with an eBay auction item e Assign an invoice number to a payment e Accept payments with giropay Germany only Additional PayPal API
21. not share your credential information with anyone Store in a secure location with limited access Credential API Certificate Registrant Gary McCue Gary McCue s Test Store San Jose CA US API Username gemccu_1229982509_biz_api1 cs com API Password DEW49XZEAXQAFMSY RequestDate May 30 2011 22 39 31 PDT Download Certificate Done Remove 6 Save the values for API Username and API Password for later use 7 Click Download Certificate and save the file PayPal Payments Pro Integration Guide April 2012 79 A Getting Started With the PayPal Name Value Pair API NVP Format 8 Rename this file to something familiar such as paypal_live_cert pem It is not necessary to keep the txt file extension Be sure to remember where you save the file After Completing This Task e If you use the PayPal SDK for Java the PayPal SDK for NET or the PayPal SDK for Classic ASP you must encrypt your certificate in PCKS12 format e If you use the PayPal SDK for NET or Classic ASP you must take additional steps to import the certificate NVP Format NVP is a way of specifying names and values in a string NVP is the informal name for the query in the URI specification The NVP string is appended to the URL An NVP string conforms to the following guidelines e The name is separated from the value by an equal sign For example FIRSTNAME Robert e Name value pairs are separated by an ampersand 82 For ex
22. of credit card information from a US buyer after the transaction amount has been determined Pay with a debit or credit card If you don t have a PayPal account Country United States ho Credit Card number vsa EJ Expiration Date mm yy CSC Whats this First name Last name Billina Address Line 1 Billing Address Line 2 Optional Zip code City State Select e g 555 555 5555 Phone Email Address NOTE In some cases the billing address and CSC value may be optional You must also identify debit on your PCI compliant checkout page when you reference a direct card checkout image 2 You must also retrieve the IP address of the buyer s browser and include this with the request 3 When a buyer clicks the Pay button invoke the DoDirectPayment API operation 4 The PayPal API server executes the request and returns a response Ack code Success Success With Warning or Failure Amount of the transaction 20 April 2012 PayPal Payments Pro Integration Guide Introducing Direct Payment E User Interface Recommendations for Direct Payment Checkout AVS response code CSC response code PayPal transaction ID Error codes and messages if any Correlation ID unique identifier for the API call 5 If the operation is successful you send the buyer to an order confirmation page The Ack code determines whether the operation is a success If successful you
23. or Premier account holder who is authorized to perform various API operations Although you can use either an API signature or a certificate for credentials PayPal recommends you use a signature IMPORTANT Although you can have both a signature and certificate you cannot use both at the same time PayPal Payments Pro Integration Guide April 2012 77 A Getting Started With the PayPal Name Value Pair API Obtaining API Credentials Creating an API Signature An API signature consists of an API username along with an associated API password and signature all of which are assigned by PayPal You need to include this information whenever you execute a PayPal API operation You must have a PayPal Business account to create a signature To create an API signature 1 Log in to PayPal then click Profile under My Account Click My selling tools 2 3 Click API Access 4 Click Request API Credentials 5 Check Request API signature and click Agree and Submit El My Account Send Money Request Money Merchant Services Products amp Services Community Overview Add Funds Withdraw History Resolution Center Profile Virtual Terminal View or Remove API Signature Back to Profile Summary i Developers Do not share your credential information with anyone Store in a secure location with limited access For preconfigured shopping carts Copy and paste the API username password and signature into your shopping car
24. period must be less than or equal to one year NOTE If the billing period is SemiMonth the billing frequency must be 1 AMT ScheduleDetails Amount to bill for each billing cycle PaymentPeriod Amount You can optionally include a value for TOTALBILLINGCYCLES SOAP field ScheduleDetails PaymentPeriod TotalBillingCycles which specifies the total number of billing cycles in the regular payment period If you either do not specify a value or specify the value 0 the payments continue until PayPal or the buyer cancels or suspends the profile If the value is greater than 0 the regular payment period continues for the specified number of billing cycles You can also specify an optional shipping amount or tax amount for the regular payment period Including an Optional Trial Period You can optionally include a trial period in the profile by specifying the following fields in the CreateRecurringPaymentsProfile request The following table lists the required fields for creating an optional trial period PayPal Payments Pro Integration Guide April 2012 67 68 Integrating Recurring Payments Options for Creating a Recurring Payments Profile Required fields for specifying a trial period NVP SOAP TRIALBILLINGPERIOD ScheduleDetails TrialPeriod BillingPeriod TRIALBILLINGFREQUENCY ScheduleDetails TrialPeriod BillingFrequency TRIALAM ScheduleDetails TrialPeriod Amou
25. the SOAP API Reference Updating Addresses When you update the subscriber shipping address you must enter all of address fields not just those that are changing To update the subscriber s street address for example specify all the address fields listed in the Name Value Pair Developer Guide and Reference or SOAP API Reference Do not specify only the street address field Updating the Billing Amount For profiles created using Express Checkout you can increase the recurring payment total amount by 20 maximum in a fixed 180 day interval after profile creation The 20 maximum is based on the total amount of the profile at the beginning of the 180 day interval including any shipping or tax amount PayPal Payments Pro Integration Guide April 2012 71 72 Integrating Recurring Payments Billing the Outstanding Amount of a Profile If for example you create a profile on March 10 with a total amount of 100 during the 180 day interval from March 10 to September 6 you can increase the amount to a maximum of 120 120 of 100 Suppose that during the first 180 day interval you increased the payment amount to 110 During the next 180 day interval starting September 7 you can only increase the amount of the payment to a maximum of 132 120 of 110 Billing the Outstanding Amount of a Profile Use the BillOutstandingAmount API to immediately bill the buyer for the current past due or outstanding amount for a recurri
26. the authorization is reversed a bank hold might remain for 7 to 10 days until reversed by the card issuer NOTE Authorizations become holds on a buyer s account that typically last 3 days for debit cards and 7 to 10 days for credit cards depending on the issuer and region If you decide not to capture an authorization you should void the transaction which triggers an authorization reversal API operations associated with the Authorization payment action in DoDirectPayment API Operation Description DoCapture Capture an authorized payment DoReauthorization Reauthorize a payment DoVoid Void an authorization DoDirectPayment Authorization and Capture Example This example authorizes a credit card payment using the DoDirectPayment API operation and then uses the DoCapture API operation to capture the payment PayPal Payments Pro Integration Guide April 2012 39 40 Getting Started With Direct Payment Direct Payment Authorization and Captures IMPORTANT Never use post actions for live transactions they are not secure In your DoDirectPayment request set the payment action to Authorization lt form method post action https sandbox paypal com nvp gt lt input type hidden name USER value gt lt input type hidden name PWD value
27. using Express Checkout and manage Express Checkout authorization and order payment actions e Sale Payment Action for Express Checkout e Authorization Payment Action for Express Checkout e Order Payment Action for Express Checkout PayPal Payments Pro Integration Guide April 2012 53 I Getting Started With Express Checkout Handling Payment Settlements With Express Checkout Sale Payment Action for Express Checkout A sale payment action represents a single payment that completes a purchase for a specified amount A sale is the default Express Checkout payment action however you can also specify the following action in your SetExpressCheckout and DoExpressCheckoutPayment requests PAYMENTREQUEST_N _PAYMENTACTION Sale A sale is the most straightforward payment action Choose this payment action if the transaction including shipping of goods can be completed immediately To use this payment action e The final amount of the payment must be known when you invoke the DoExpressCheckoutPayment API operation e You should intend to fulfill the order immediately such as would be the case for digital goods or for items you have in stock for immediate shipment After you execute the DoExpressCheckoutPayment API operation the payment is complete and further action is unnecessary You cannot capture a further payment or void any part of the payment when you use this payment action Authorization Payment
28. 0 must be specified as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00 regardless of the currency used PAYMENTREQUEST_0_AMT amount PAYMENTREQUEST_0_CURRENCYCODE currencylD 4 Specify the return URL The return URL is the page to which PayPal redirects your buyer s browser after the buyer logs into PayPal and approves the payment Typically this is a secure page hnttps on your site NOTE You can use the return URL to piggyback parameters between pages on your site For example you can set your Return URL to specify additional parameters using the https www yourcompany com page html param value syntax The parameters become available as request parameters on the page specified by the Return URL RETURNURL retum_url 5 Specify the cancel URL The cancel URL is the page to which PayPal redirects your buyer s browser if the buyer does not approve the payment Typically this is the secure page https on your site from which you redirected the buyer to PayPal April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout CEN Implementing the Simplest Express Checkout Integration NOTE You can pass SetExpressCheckout request values as parameters in your URL to have the values available if necessary after PayPal redirects to your URL CANCELURL cancel_url 6 Specify the payment action Although the defaul
29. 3851788972286RECEIPTID 007 RANSACTIONTYPE webaccept amp PAYMENTTYPE instant amp EXPECT E 1970 2d01 2d01T00 3a00 3a00Z amp 0RDERT IME 2010 2d03 2d08T19 EAMT 0 2e45 amp TAXAMT 0 2e00 amp CURRENCYCODE USD amp PAYMENTS PENDINGRI EASON NonegREASONCODE NonesPROTECTIONELIGIBILITY 1n NOTE The DoCapture response returns a new transaction ID as well as the authorization ID The authorization ID is also the parent transaction ID for the completed transaction DoDirectPayment Reauthorization and Capture Example This example authorizes a credit card payment using the DoDirectPayment API operation and then reauthorizes the payment using the DoReauthorization API operation before capturing it with the DoCapture API operation IMPORTANT Never use post actions for live transactions they are not secure In your DoDirectPayment request set the payment action to Authorization PayPal Payments Pro Integration Guide April 2012 41 4 Getting Started With Direct Payment Direct Payment Authorization and Captures lt form method post action https sandbox paypal com nvp gt lt input type hidden name USER value gt lt input type hidden name PWD value gt l
30. 6b174e9bac3b3 amp ACK Success amp VERS ION XX 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M amp EMATL YourSandboxBuyerAccountEmail amp PAYERID 7AKUSARZ7SAT8 amp PAYERSTATUS verified amp FIRSTNAME amp LASTNAME amp COUNTRYCODE US amp BUSINESS amp PAYMENTREQUEST_0_SHIPTONAME amp PAYMENTREQUEST_0_SHIPTOSTREET amp PAYMENTREQUEST_0_SHIPTOCITY amp PAYMENTREQUEST_0_SHIPTOSTATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME United 20States amp PAYMENTREQUEST_0_SHIPTOZIP 94666 amp PAYMENTREQUEST_0_ADDRESSID PAYMENTREQUEST_0_ADDRESSSTATUS Confirmed 6 Invoke a form on your site that invokes the DoExpressCheckout Payment API operation on the Sandbox 52 April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout CE Handling Payment Settlements With Express Checkout lt form method post action https api 3t sandbox paypal com nvp gt lt input type hidden name USER value API_username gt lt input type hidden name PWD value API_passwora gt lt input type hidden name SIGNATURE value API_signature gt lt input type hidden name V
31. 84 amp EXPDATE 042011 amp CVV2 123 SFIRSTNAME John amp LASTNAME Smith amp STREET 1 Main St amp CITY San Jose amp STATE CA amp ZIP 95131 amp COUNTRYCODE US 2 Test that the response to the DoDirectPayment API operation was successful The ACK field must contain Success or SuccessWithWarning however other fields in the response can help you decide whether to ultimately accept or refund the payment TIMESTAMP amp CORRELATIONID amp ACK Success amp VERS ION 56 2e0 amp BUILD 1195961 AMT 8 2e88 amp CURRENCYCODE USD amp AVSCODE X amp CVV2MATCH M amp TRANSACTIONID NOTE Values of status fields are simulated because an actual card transaction does not occur 3 Log into your PayPal test account from the Sandbox On the My Account Overview page you should see the results of your transaction if the transaction was successful PayPal Payments Pro Integration Guide April 2012 35 4 Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL PayPal Sandbox Test Site LogQut sseui PayPal My Account Send Money Request Money Merchant Services Products amp Services Community Overview AddFunds Withdraw History Resolution Center Profile Virtual Terminal Welcome Doco Fi Business Name Doco Fis Test Store Account Type Business Stat
32. ATURE value gt lt input type hidden name VERSION value 62 0 gt lt input name AUTHORIZATIONID value 6HB59926VL998415S gt lt input name AMT value 45 gt lt input name CURRENCYCODE value USD gt lt input name COMPLETETYPE value Complete gt lt input name INVNUM value gt lt input name NOTE value gt lt input name SOFTDESCRIPTOR value gt lt input type submit name METHOD value DoCapture gt lt form gt If the capture was successful the payment status is Completed AUTHOR TZ AT IONID 6HB5 992 6VL998415S amp TIMESTAMP 2010 2d03 2d08T21 3a06 3a012Z amp CO RRELATIONID 8 955b8704da91 amp ACK Success amp VERS ION 62 2e0 amp BUILD 1218643 amp TRANSACT TONID 2BG77878LE143642C amp PARENTTRANSACT IONID 4HS1916972552122T amp RECEIPTID 111 5 208794 2d3120 2d68 92 amp TRANSACT IONTYPE webaccept amp PAYMENTTYPE instant amp EXPECT EDECHECKCLEARDATE 1 970 2d01 2d01T00 3a00 3a00Z amp O0RDERT IME 2010 2d03 2d08T21 3a06 3a00Z amp AMT 45 2e00 amp FEEAMT 1 2e61 amp TAXAMT 0 2600 amp CURRENCYCODE USD amp PAYMENT STATUS Completed amp PEND INGREASON None amp REASONCODE None amp PROTECTIONELIGIBILITY I1 neligible NoTE The DoCapture response returns a new transaction ID as well as the authorization ID associated with the reauthorization The authorization ID is also the parent transaction ID for the completed tr
33. Action for Express Checkout An authorization payment action represents an agreement to pay and places the buyer s funds on hold for up to three days To set up an authorization specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests PAYMENTREQUEST_N PAYMENTACTION Authorization An authorization enables you to capture multiple payments up to 115 of or USD 75 more than the amount you specify in the DoExpressCheckoutPayment request Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately The honor period for which funds can be held is three days The valid period for which the authorization is valid is 29 days You can reauthorize the 3 day honor period at most once within the 29 day valid period You can void an authorization in which case the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured If no part of the payment has been captured the entire payment becomes void and nothing can be captured April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout CEN Handling Payment Settlements With Express Checkout API operations associated with Authorization payment action in Express Checkout API Operation Description DoCapture Capture an authorized paym
34. ENTREQUEST_0_AMT value 19 95 gt lt input type hidden name RETURNURL R value https www YourReturnURL com gt lt input type hidden name CANCELUR value https www YourCancelURL com gt lt input type submit name METHOD value SetExpressCheckout gt lt form gt E c NOTE Use an API username from a Sandbox business test account for which a signature exists See the Test Certificates tab of the Sandbox to obtain a signature If you are not using a signature you must use a different Sandbox server 2 Review the response string from the SetExpressCheckout API operation PayPal responds with a message such as the one shown below Note the status which should include ACK set to Success and a token that is used in subsequent steps TIMESTAMP 2007 2d04 2d05T23 3a23 3a07Z CORRELATIONID 63cdac0b67b50 amp ACK Success amp VERS ION XX 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M 3 If the operation was successful use the token and redirect your browser to the Sandbox to log in as follows https www sandbox paypal com cgi bin webscr cmd _express checkout token EC 1NK66318YB71 7835M You may need to decode the URL which is the opposite of URL encoding by replacing hexadecimal codes with ASCII codes for example you may need to replace 2d in the token with a hyphen You must log in to
35. ERSION value XX 0 gt lt input type hidden name PAYMENTREQUEST_0_PAYMENTACTION value Authorization gt lt input type hidden name PAYERID value 7AKUSARZ7SAT8 gt lt input type hidden name TOKEN value EC 2d1NK66318YB717835M gt lt input type hidden name PAYMENTREQUEST_0_AMT value 19 95 gt lt input type submit name METHOD value DoExpressCheckoutPayment gt lt form gt 7 Review the response string from the DoExpressCheckoutPayment API operation If the operation was successful the response should include ACK set to Success as follows TIMESTAMP 2007 2d04 2d05T23 3a30 3a162Z CORRELATIONID 333fb808bb23 ACK Success S VERSTON XX3 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M PAYMENTREQUEST_0_TRANSACTIONID 0431444401487742J PAYMENTREQUEST_0_TRANSACTIONTYPE expresscheckout PAYMENTREQUEST_0_PAYMENTTYPE instant amp PAYMENTREQUEST_0O_ORDERTIME 2007 2d04 2d05T23 3a30 3a14Z amp PAYMENTREQUEST_0O_AMT 19 2e95 PAYMENTREQUEST_0_ CURRENCYCODE USD PAYMENTREQUEST_0_TAXAMT 0 2e00 PAYMENTREQUEST_0_PAYMENTSTATUS Pending PAYMENTREQUEST_0_PENDINGREASON authorization PAYMENTREQUEST_0_ REASONCODE None Handling Payment Settlements With Express Checkout You can use PayPal API operations to handle the capture of payments authorized
36. KEN field The following table lists the fields that are required in the CreateRecurringPaymentsProfile request for recurring payments using direct payments Required fields for CreateRecurringPaymentsProfile in Direct Payment NVP SOAP CREDITCARDTYPI CreditCardDetails CreditCardType E ACCT CreditCardDetails CreditCardNumber EXPDATE CreditCardDetails ExpMonth and CreditCardDetails ExpYear FIRSTNAME CreditCardDetails CardOwner PayerName FirstName LASTNAME CreditCardDetails CardOwner PayerName LastName PROF ILESTARTDATI RecurringPaymentProfileDetails BillingStartDate E BILLINGPERIOD ScheduleDetails PaymentPeriod BillingPeriod BILLINGFREQUENCY ScheduleDetails PaymentPeriod BillingFrequency AMT ScheduleDetails PaymentsPeriod Amount PayPal Payments Pro Integration Guide April 2012 61 E Integrating Recurring Payments Recurring Payments With the Express Checkout API The CreateRecurringPayment sProfile response contains a Profile ID which is an encoded string that uniquely identifies the recurring payments profile For more options when creating a recurring payments profile see Options for Creating a Recurring Payments Profile on page 66 As with all direct payments PayPal is completely invisible to your buyer before during and after the purchase PayPal does not s
37. N Issuing Refunds AMT amount CURRENCYCODE CcurrencylD 4 For a partial refund specify the memo description NOTE description 5 Execute the RefundTransact ion operation 6 Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful PayPal Payments Pro Integration Guide April 2012 57 I Getting Started With Express Checkout Issuing Refunds 58 April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments Both Direct Payment and Express Checkout support recurring payments You can set up a recurring payment to handle a subscription and other payments that occur on a fixed schedule e How Recurring Payments Work e Recurring Payments Terms e Recurring Payments With Direct Payment e Recurring Payments With the Express Checkout API e Options for Creating a Recurring Payments Profile e Recurring Payments Profile Status e Getting Recurring Payments Profile Information e Modifying a Recurring Payments Profile e Billing the Outstanding Amount of a Profile e Recurring Payments Notifications How Recurring Payments Work To view a video that demonstrates how to set up Recurring Payments navigate to Recurring Payments Demo When you support recurring payments for a buyer you create a recurring payments profile The profile contains information about the recurring payments including details for an optional trial period and a regular payment period
38. NVP API for more information about the PayFlow API see Gateway Developer Guide and Reference e PayPal API Client Server Architecture e Obtaining API Credentials e Creating an NVP Request e Executing NVP API Operations e Responding to an NVP Response PayPal API Client Server Architecture The PayPal API uses a client server model in which your website is a client of the PayPal server A page on your website initiates an action on a PayPal API server by sending a request to the server The PayPal server responds with a confirmation that the requested action was taken or indicates that an error occurred The response might also contain additional information related to the request The following diagram shows the basic request response mechanism Your Site Request Checkout L rre rro a i PayPal Add To Cart H Response API Server Tha salas re wuy la pay For example you might want to obtain the buyer s shipping address from PayPal You can initiate a request specifying an API operation to obtain buyer details The response from the PayPal API server contains information about whether the request was successful If the operation succeeds the response contains the requested information In this case the response contains the buyer s shipping address If the operation fails the response contains one or more error messages PayPal Payments Pro Integration Guide April 2012 75 A Getting Started With the PayPal Name Value Pa
39. Operations You can use PayPal API operations to include advanced processing and back office processes with Express Checkout You can e Capture payments associated with authorizations and orders e Process recurring payments e Issue refunds search transactions using various criteria and provide other back office operations PayPal Payments Pro Integration Guide April 2012 25 4 Introducing Express Checkout Express Checkout Flow Express Checkout Flow To implement Express Checkout you must offer it both as a checkout option and as a payment method Typically you initiate the Express Checkout flow on your shopping cart page and on your payment options page You add Express Checkout to your existing flow by placing the Checkout with PayPal button on your Shopping Cart page and by placing the PayPal mark on your Payment Methods page The following diagram shows the complete flow Continue a a Choose a way Review your to pay information O A O gt Checkout K K Confirmation gt Add Ta Can gt Collect shipping gt Confirm order Order The catas asatar way lo pay address VISA ES confirmation Shopping cart Payment methods Make the following changes to implement the complete Express Checkout flow e On your Shopping cart page place the Checkout with PayPal button Handle clicks by sending the Express Checkout setup request After receiving the response redirect your buyer s browser to PayPal
40. PayPal PayPal Payments Pro Integration Guide PayPal Payments Pro Integration Guide Document Number 100001 en_US 201204 2010 2011 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described here
41. Set to the returned EciFlag value XID XID Set to the returned Xid value 92 April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only Boo Website Setup Flow of field values among requests and responses Not all fields are shown Signaturo Verification Payload P pabed PaRos P gt PARosPayioad PARosStatus b AUTHSTATUSIDS Example DoDirectPayment request The following example shows the additional fields required for 3 D Secure transactions refer to the DoDirectPayment documentation for all required fields METHOD DoDirectPayment amp amp ECI3DS 5 amp CAVV OTJ1IMzViODhiOT11MjBhYmVkMGU amp AUTHSTATUS3DS Y amp MP I VENDOR3DS Cardinal amp VERS ION 59 0 Website Setup Cardinal and or 3 D Secure require that you add specific elements to your web pages These include e Integrate the authentication window to allow for consistent site branding during the authentication process e Display the Visa and MasterCard Learn More logos on your home and check out pages e Provide text and logo on the check out page in which you collect payment information Notify the cardholder that they may be required to provide their authentication password e Notify the cardholder of authentication results Refer to the Cardinal Thin Client Integration Guide for details PayPal Payments Pro Integration Guide April 2012 93 B Implementing 3 D Secure Transactions UK O
42. T_0_QOTYO 1 Response Parameters successResponseFields PROFILEID I G7ALAX8095JY amp PROFILESTATUS Active Options for Creating a Recurring Payments Profile You can create a recurring payments profile that allows a regular payment period an optional trial period an initial payment and other options Specifying the Regular Payment Period Each recurring payments profile has a regular payment period that defines the amount and frequency of the payment The following table lists the required fields for specifying the regular payment period 66 April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments EN Options for Creating a Recurring Payments Profile Required fields for specifying a regular payment period NVP SOAP Description PROFILESTARTDATE RecurringPaymentsProfileDet The date when billing for this profile ails BillingStartDate begins NOTE The profile may take up to 24 hours for activation BILLINGPERIOD ScheduleDetails The unit of measure for the billing cycle PaymentPeriod BillingPeriod Must be one of the following e Day e Week e SemiMonth e Month e Year BILLINGFREQUENCY ScheduleDetails The number of billing periods that make PaymentPeriod BillingFreque up one billing cycle The combination of ncy billing frequency and billing
43. a MasterCard Visa MasterCard Dollar Swedish Krona SEK Visa MasterCard Visa MasterCard Swiss Franc CHF Visa MasterCard Visa MasterCard U S Dollar USD Visa MasterCard Visa MasterCard Visa MasterCard Discover American Express NOTE Virtual Terminal for France supports the same currencies as Visa or MasterCard for the UK Express Checkout supports all of the countries identified in the table 16 April 2012 PayPal Payments Pro Integration Guide Introducing PayPal Payments Pro A Website Payments Pro Regional Differences Addresses e For Canada specify the province abbreviation in the State field e For Great Britain the State field is ignored however you still may need to specify a value in the State field for example you can specify the city for both the city and state For more information about addresses see the PayPal Developer Network PayPal Payments Pro Integration Guide April 2012 17 p Introducing PayPal Payments Pro Website Payments Pro Regional Differences 18 April 2012 PayPal Payments Pro Integration Guide Introducing Direct Payment Direct Payment lets buyers who do not have a PayPal account use their credit cards without leaving your website PayPal processes the payment in the background e The Direct Payment User Experience e User Interface Recommendations for Direct Payment Checkout The Direct Payment User Experience Direct Payment enables buyers to pay by cred
44. a protocol developed by the card schemes that improves the security of Internet payments that are not within a closed loop checkout option such as PayPal It allows merchants to authenticate cardholders through the cards issuers Its goals are to reduce the likelihood of fraud when using supported cards and to improve transaction performance Merchants who do not use 3 D Secure may be liable for fraudulent transactions even if the transaction was authorized by other means Visa offers 3 D Secure under the name Verified by Visa and MasterCard offers it as MasterCard SecureCode PayPal enables you to pass 3 D Secure data to PayPal for Payments Pro transactions but you must obtain the 3 D Secure authentication data from the card s issuer PayPal has an agreement with Cardinal Commerce that allows Payments Pro merchants free access to Cardinal s 3 D Secure technology Cardinal Centinel The Cardinal Centinel Thin Client interface provides access to payer authentication for transactions using Visa MasterCard and Maestro branded cards Use of 3 D Secure authentication is optional for Visa and MasterCard transactions PayPal Payments Pro Integration Guide April 2012 87 88 Implementing 3 D Secure Transactions UK Only Integration Overview 3 D Secure is not supported for direct Recurring Billing and Reference Transactions Cards that require 3 D Secure authentication cannot use these APIs however cards where 3 D Secure is optional can con
45. all Express Checkout API operations For direct payment it occurs when you make an explicit call to set up the billing agreement Recurring payments using reference transactions is an alternative which enables you to handle payments for varying amounts of money on a varying schedule A reference transaction is a financial transaction from which subsequent transactions can be derived for example a buyer can make a purchase on your site and the PayPal transaction ID called a reference transaction ID can later be used to initiate another transaction NOTE The use of recurring payments with direct payment may incur additional fees Virtual Terminal PayPal s Virtual Terminal is a web based application that allows you to accept credit card payments It is available to merchants in the United States Canada France and the United Kingdom Virtual Terminal provides your business with the functionality similar to a stand alone credit card processing terminal Virtual Terminal is ideal when you receive orders by PayPal Payments Pro Integration Guide April 2012 11 12 Introducing PayPal Payments Pro Additional Features of PayPal Payments Pro phone fax or by mail and want to accept credit cards An optional card reader is available to process face to face purchases however some restrictions apply You can use Virtual Terminal on any computer with an internet connection and a web browser For more information about Virtual Terminal see V
46. ample FIRSTNAME Robert amp MIDDLENAME Herbert LASTNAME Moore e The values for each value in an NVP string are URL encoded Creating an NVP Request The Name Value Pair request format specifies the API operation to perform credentials that authorize PayPal to access your account and fields containing additional information to be used in the request Specifying the PayPal API Operation For the NVP version of the PayPal API you must specify the name of the PayPal API operation to execute in each request along with the version of the API operation The following diagram shows the API operation part of an NVP request 80 April 2012 PayPal Payments Pro Integration Guide Getting Started With the PayPal Name Value Pair API onl Creating an NVP Request Your Site p NVP Request T Chachas 1 METHOD SetExpressCheckout Add To Cart VERSION XX 0 ES PayPal API credentials API Server E Request specific fields The satan samar way le piy A method specifies the PayPal operation you want to execute and each method is associated with a version Together the method and version define the exact behavior of the API operation Typically the behavior of an API operation does not change between versions however you should carefully retest your code whenever you change a version To specify a method and version number 1 Choose the PayPal API operation you want to use METHOD 0peration 2 Choo
47. anations and recommended actions Cardinal transaction information that you will pass to other requests Transactionld Enrolled Payload and EciFlag ACSUrl If Enrolled Y this contains the URL for the card issuer s bank s authentication site Evaluate Enrolled and ACSUrl If cardholder is not enrolled Enrolled is N or if the Authentication service is unavailable ACSUr1 is U or N continue with Step 5 below If cardholder is enrolled continue with the next step 3 Using an HTTP form POST pass the cardholder to the URL ACSUr1 returned by cmpi_lookup which is the card issuer s authentication URL Pass several fields to this request Transaction information from cmpi_lookup MD field optionally containing arbitrary merchant data set to blank if not used TermUrl The URL of the page you set up to handle the issuer s return call See Issuer Authentication Request for the complete list of required fields Cardholders attempt to authenticate themselves at the issuer s URL The completion of the attempt returns a response to your application by using HTTP Form POST to call the URL you specified in TermUr1 The response contains the PaRes 4 Call cmpi_authenticate passing PaRes as PAResPayLoad This interprets the payload to determine whether the cardholder passed the authentication process with the card s issuer See cmpi_authenticate API for the
48. ansaction PayPal Payments Pro Integration Guide April 2012 43 4 Getting Started With Direct Payment Direct Payment Authorization and Captures 44 April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout To implement Express Checkout start with the simplest Express Checkout integration and test it Then you can decide the kind of payment settlement actions you want to support e Implementing the Simplest Express Checkout Integration e Testing an Express Checkout Integration e Handling Payment Settlements With Express Checkout e Issuing Refunds Implementing the Simplest Express Checkout Integration The simplest Express Checkout integration requires the following PayPal API operations SetExpressCheckout DoExpressCheckoutPayment and optionally GetExpressCheckoutDetails e Setting Up the Express Checkout Transaction e Obtaining Express Checkout Transaction Details e Completing the Express Checkout Transaction Setting Up the Express Checkout Transaction To set up an Express Checkout transaction you must invoke the SetExpressCheckout API operation to provide sufficient information to initiate the payment flow and redirect to PayPal if the operation was successful This example assumes that you have set up the mechanism you will use to communicate with the PayPal server and have a PayPal Business account with API credentials It also assumes that the payment action is a final sale W
49. at PayPal Payments Pro Integration Guide April 2012 85 A Getting Started With the PayPal Name Value Pair API Responding to an NVP Response Format of an Error Response Response Fields on ACK notSuccess TIMESTAMP date timeOfResponses Multiple errors can be Error CORRELATIONID debuggingTokensVERSION VersionNos returned Each set of BUILD buildNumber amp L_ERRORCODE0 errorCodes errors has a different numeric suffix starting L_SHORTMESSAGE0 shortMessage amp x a with 0 and incremented LONGMESSAGEO longMessages by one for each error SEVERITYCODE0 severityCode Additional pass through information may appear in the L_ERRORPARAMIDn and L_ERRORPARAMVALUEn fields Consider the following error response TIMES TAMP 2011 2d11 2d15T20 3a27 3a02Z amp CORRELAT IONID 5be53331d9700 amp ACK Fail ure amp VERS ION 78 2e0 amp BUILD 000000 amp L_ERRORCODE0 15005 amp L_SHORTMESSAGE0 Processo r 20Decline amp L_LONGMESSAGE0 This 20transaction S20cannot 20be 20processed S2e amp L_SEVERITYCODE0 Error amp L_ERRORPARAMID0 ProcessorResponse amp L_ERRORPARAMVALUEO 0051 AMT 10 2e40 amp CURRENCYCODE USD amp AVSCODE X amp CVV2MATCH M In this case the parameter ID is ProcessorResponse which indicates an error response by a credit or debit card processor The value contains the processor spec
50. ate may not be earlier than the profile creation date Recurring Payments with Express Checkout also has the following limitations e To be able to create a recurring payments profile for the buyer you must ensure that the buyer s PayPal account includes an active credit card e You can create amaximum of 10 recurring payments profiles during checkout e You can increase the profile amount by only 20 in each 180 day interval after you create the profile Recurring Payments Terms The following table lists and describes terms that are commonly used in the context of PayPal recurring payments Recurring Payments Terms Term Definition Recurring payments profile Your record of a recurring transaction for a single buyer The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval Billing cycle Make one payment per billing cycle Each billing cycle has 2 components e The billing period specifies the unit to calculate the billing cycle such as days or months e The billing frequency specifies the number of billing periods that make up the billing cycle For example if the billing period is Month and the billing frequency is 2 the billing cycle is 2 months If the billing period is Week and the billing frequency is 6 PayPal schedules the payments every 6 weeks Regular payment period The main subscription period for this profile which defines a payment amount
51. ayment methods page by selecting PayPal as the default option The following diagram shows how to integrate Express Checkout from your payment methods page login Conte a a Choose a way Review your to pay information 4 y A TI A A A gt gt gt gt hdd To Can am Collect shipping Confirm order Order ee address Paypa VISA ES confirmation Shopping cart Payment methods Express Checkout Building Blocks You implement Express Checkout flows with Express Checkout buttons PayPal API operations PayPal commands and tokens The following conceptual diagram identifies the building blocks that you use to integrate Express Checkout on your website PayPal Payments Pro Integration Guide April 2012 27 28 Introducing Express Checkout Express Checkout Building Blocks Legend Callouts ul Merchant Website Me PayPal Website PayPal redirects customer to merchant site Add PayPal Checkout button Call GetExpressCheckoutDetails API Checkout Confirmation ana E aw e T gt a Pay Now Choose a way Review your Confirm order Order ape eprom to pay information confirmation Shopping cart Call SetExpressCheckout API Call DoExpressCheckoutPayment API Redirect customer to PayPal A token is a value assigned by PayPal that associates the execution of API operations and commands with a specific instance of a user experience flow NOTE Tokens are not shown in the diagram PayPal Button and Logo Images To i
52. btain the Payer ID by calling the GetExpressCheckoutDetails API PAYERID id 5 Specify the amount of the order including shipping handling and tax include the currency if it is not in US dollars Most of the time this will be the same amount as you specified in your SetExpressCheckout call adjusted for shipping and taxes PAYMENTREQUEST_0_AMT amount PAYMENTREQUEST_0_CURRENCYCODE currencylD 6 Specify the same payment action that you specified in SetExpressCheckout PAYMENTREQUEST_0_PAYMENTACTION Sale Testing an Express Checkout Integration You can test your Express Checkout integration in the Sandbox This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms You can use this strategy for your initial testing however for more complete testing you need to replace these forms with your web pages containing your actual code PayPal Payments Pro Integration Guide April 2012 49 I Getting Started With Express Checkout Testing an Express Checkout Integration The following diagram shows the Express Checkout execution flow which uses the Sandbox as the API server The pages on the left represent your site Legend aa Web Flow P API Call O Token ler it vent Pa a Checkout AAA AAA Request SetExpressCheckout PayPal Add To Gant Que Response Token 9 Sandbox The se as p
53. ck out with PayPal button is the image you place on your shopping cart page The US version of the image looks like this The safer easier way to pay To create an Express Checkout button see https www paypal com us cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside PayPal also provides buttons for other countries To locate a page for another country replace the country abbreviation in the link with another country abbreviation For example replace us with uk for United Kingdom as follows https www paypal com uk cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside PayPal hosts images for the countries Country specific buttons and images URL URL URL URL Country Change Country Change Country Change Country Change Australia au Austria at Belgium be Canada ca China cn France fr Germany de Italy it Japan jl Netherlands nl Poland pl Spain es Switzerland ch United uk United us Kingdom States NOTE URL changes are case sensitive The abbreviation in the URL may not be a country code Payment Mark The PayPal mark is the image you place on your payment methods page It looks like this PayPal To implement PayPal as a payment option which is part of the Express Checkout experience associate the PayPal mark image with your payment options PayPal recommends using radio buttons for payment options Payment Options a ad ES vs G Fy PayPal Payments Pro In
54. collect a payment for each shipment e Drop shipments which are shipments from other vendors for which you accept the payment You cannot reauthorize an authorization You handle the need to reauthorize for example when the hold period or valid period of an authorization expires simply by creating another authorization You can void an order or an authorization created from the order If you void an order the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured If no part of the payment has been captured the entire payment becomes void and nothing can be captured If you void an authorization associated with the order the uncaptured part of the amount specified in the authorization becomes void and can no longer be captured If no part of the authorization has been captured the entire authorized payment becomes void PayPal Payments Pro Integration Guide April 2012 55 56 Getting Started With Express Checkout Issuing Refunds API operations associated with Order payment action in Express Checkout API Operation Description DoAuthorization Authorize a payment DoCapture Capture an authorized payment DoVoid Void an order or an authorization Issuing Refunds You can use the RefundTransaction PayPal API operation to issue refunds Use the RefundTransaction API to issue one or more refunds associated with a transaction such as a transaction c
55. ct Payment core API operations Direct Payment only DoDirectPayment Process a credit card payment such as a sale or authorization DoNonReferencedCredit Issue a credit to a card not referenced by the original transaction NOTE Contact PayPal to use this API operation in most cases you should use the RefundTransaction API operation instead Express Checkout core API operations Express Checkout only SetExpressCheckout Initiates an Express Checkout transaction GetExpressCheckoutDetails Obtain information about an Express Checkout transaction DoExpressCheckoutPayment Completes an Express Checkout transaction Common API operations GetTransactionDetails Obtain information about a specific transaction ManagePendingTransactionStatus Accept or deny a pending transaction held by Fraud Management Filters RefundTransaction Issue a refund to the PayPal account holder associated with a transaction TransactionSearch Search transaction history for transactions that meet the specified criteria Authorization and Capture API operations DoCapture Capture an authorized payment DoAuthorization Authorize a payment Express Checkout only PayPal Payments Pro Integration Guide April 2012 13 Introducing PayPal Payments Pro PayPal Payments Pro API Operations PayPal API Operation Description DoReauthorization DoVoid Recurring Payment API operations CreateRecurringPaymentsProfile GetRecurringPaymentsPr
56. e SIGNATURE API_signature 4 Optionally you can specify the email address on file with PayPal of the third party merchant on whose behalf you are calling the API operation SUBJECT merchantEmailAddress NOTE Typically a merchant grants third party permissions to a shopping cart The merchant previously must have given you permission to execute the API operation Specifying Credentials Using cURL The following example shows one way to specify a signature using CURL curl insecure https api 3t sandbox paypal com nvp d ME THOD name amp VERS ION XX 0 amp USER API_username amp PWD API_password SIGNATURE API_ signature fee NOTE This example does not establish a secure connection and should not be used live on paypal com URL Encoding All requests to execute PayPal API operations sent using HTTP must be URL encoded The encoding ensures that you can transmit special characters characters that are not allowed in a URL and characters that have special meaning in a URL such as the equal sign and ampersand The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server You must encode all data sent using the HTTP protocol because data that is not encoded could be misinterpreted as part of the HTTP protocol instead of part of the request Most programming languages provide a way to encode strings in this way You April 2012 PayPal Payme
57. e initial payment or canceled the pending profile Maximum Number of Failed Payments By including the MAXFATLEDPAYMENTS field in the CreateRecurringPaymentsProfile request you set the number of failed payments allowed before PayPal automatically suspends the profile PayPal sends you an IPN message when the number of failed payments reaches the maximum number specified April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments EN Recurring Payments Profile Status Billing the Outstanding Amount If a payment fails for any reason PayPal adds the billing amount including shipping and tax if applicable to the profile s outstanding balance Use the AUTOBILLOUTAMT field in the CreateRecurringPaymentsProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle Whether or not you choose to include the outstanding amount with the payment for the next billing cycle you can also use the BillOutstandingAmount API to programmatically collect that amount at any time Identifying Items as Digital or Physical Goods Set all the payment details item fields in the following table in the CreateRecurringPaymentsProfile request If all items are digital goods be sure to set the item category field to Digital to get the discount rate for digital goods Required fields for specifying item details
58. e transaction in cents or pence with no decimal point For example 100 is specified as 10000 Required The 3 digit numeric ISO 4217 currency code for the sale amount For example GBP 826 EUR 978 Required The debit or credit card number up to 19 digits with no nonnumeric characters Required The card s expiration month formatted as MM Required The card s expiration year formatted as YYYY Required Your order number or transaction identifier Limited to 50 characters Optional Cardinal allows several additional optional fields which you can choose to use Refer to the Cardinal documentation for details cmpi_lookup Response cmpi_lookup Response Fields Field ErrorNo ErrDesc Description Error number 0 indicates no error Empty if there is no error otherwise describes the error April 2012 PayPal Payments Pro Integration Guide Issuer Authentication Fields Implementing 3 D Secure Transactions UK Only Boo Field Description Transactionld Centinel transaction identifier Identifies the transaction within Centinel Enrolled Status of authentication eligibility If not Y then the cardholder is not eligible for authentication Possible values are e Y Enrolled e N Not enrolled e U Cardholder authentication unavailable ACSUrl If Enrolled Y this contains the URL to which your application must next send the cardholder to complete authentication Payload If Enro
59. eckout Integration 45 Setting Up the Express Checkout Transaction 2 000054 45 Obtaining Express Checkout Transaction Details 4 47 Completing the Express Checkout Transaction 2 0000 4 48 Testing an Express Checkout Integration ee 49 Handling Payment Settlements With Express Checkout 53 Sale Payment Action for Express Checkout 0 0 e 54 Authorization Payment Action for Express Checkout o 54 Order Payment Action for Express Checkout 0 e 55 ISSUING ASTUNOS sexto ra a RTE TRR Z a ek we GE a GG a aa 56 Chapter 6 Integrating Recurring Payments 59 How Recurring Payments Work 2 2 1 o e eo 59 LIMITACI N ew a ee DR OR OR a Ae A ew a a a ee 60 Recurring Payments Terms 2 2 ee 60 Recurring Payments With Direct Payment 2222200 61 Recurring Payments With the Express Checkout API aoaaa aaa 62 Initiating the Processing Flow With SetExpressCheckout 63 4 April 2012 PayPal Payments Pro Integration Guide Contents E Redirecting the Buyer to PayPal o o o 64 Getting Buyer Details Using GetExpressCheckoutDetails 65 Creating the Profiles With CreateRecurringPaymentsProfile 65 Options for Creating a Recurring Payments Profile 66
60. efault transaction limit in default currency Canada 12 500 CAD United Kingdom 5 500 GBP United States 10 000 USD NOTE Contact PayPal if you want to increase transaction limits PayPal Payments Pro Integration Guide April 2012 15 a Introducing PayPal Payments Pro Website Payments Pro Regional Differences Credit Card Currencies by Country The following currencies are supported for Direct Payment Currencies and Currency Codes Supported by Express Checkout and Direct Payment Direct Payment Express Cur Currency for Direct Payment Direct Payment Checkout rency Specified Card in Currency for Specified Currency for Specified Currency Code United States Card in United Kingdom Card in Canada Australian AUD Visa MasterCard Visa MasterCard Visa MasterCard Dollar Canadian CAD Visa MasterCard Visa MasterCard Visa MasterCard Dollar Czech Koruna CZK Visa MasterCard Visa MasterCard Danish Krone DKK Visa MasterCard Visa MasterCard Euro EUR Visa MasterCard Visa MasterCard Visa MasterCard Hong Kong HKD Visa MasterCard Visa MasterCard Dollar Hungarian HUF Visa MasterCard Visa MasterCard Forint Japanese Yen JPY Visa MasterCard Visa MasterCard Visa MasterCard Norwegian NOK Visa MasterCard Visa MasterCard Krone New Zealand NZD Visa MasterCard Visa MasterCard Dollar Polish Zloty PLN Visa MasterCard Visa MasterCard Pound Sterling GBP Visa MasterCard Visa MasterCard Maestro Visa MasterCard Singapore SGD Vis
61. end an email receipt to the buyer nor will the buyer s credit card statement indicate that PayPal processed the payment Recurring Payments With the Express Checkout API During the checkout flow you can create one or more recurring payments and mix recurring payments with other purchases The following diagram illustrates the typical processing flow to create recurring payments during checkout Legend aa Web Flow gt API Call O Token Y Profile ID lercha ti ayPal Payment Pages e A es ROQUES 7 Giet SotExpressCheckout PayPal 209 To an Que Response Token O API Server Smee PayPal The tn came way la pay Merchant website S L HTTP Redirect mm da P O HTTP Redirect ME P iD Recept e Request Token e GetExpressCheckoutDetails PayPal Pay Now A lt m Response Customer Details API Server y IA mn Request Final Transaction Details O gt DoExpressCheckoutPayment IS ti Response Transaction Results m PayPal mo Request Final Transaction Details O b API Server CreateRecurringPaymentsProfile O a Y Response Transaction Results m Profile ID Success Failure 62 April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments CEN Recurring Payments With the Express Checkout API The circled numbers in the diagram correspond to the numbered steps in the following table Recurring payments processing flow Step Merchant PayPal
62. ent When you redirect your buyer s browser to PayPal you must specify the ExpressCheckout command for Express Checkout You also specify the token that identifies the transaction which was returned by the SetExpressCheckout API operation NOTE To enable PayPal to redirect back to your website you must have already invoked the SetExpressCheckout API operation specifying URLs that PayPal uses to redirect back to your site PayPal redirects to the success URL when the buyer pays on PayPal otherwise PayPal redirects to the cancel URL If the buyer approves the payment PayPal redirects to the success URL with the following information e The token that was included in the redirect to PayPal e The buyer s unique identifier Payer ID If the buyer cancels PayPal redirects to the cancel URL with the token that was included in the redirect to PayPal April 2012 PayPal Payments Pro Integration Guide Introducing Express Checkout PU Express Checkout Building Blocks Express Checkout Token Usage Express Checkout uses a token to control access to PayPal and execute Express Checkout API Operations The SetExpressCheckout API operation returns a token which is used by other Express Checkout API operations and by the _ExpressCheckout command to identify the transaction The life of the token is approximately 3 hours PayPal Payments Pro Integration Guide April 2012 31 T Introducing Express Checkout Express Checkout Build
63. ent DoReauthorization Reauthorize a payment DoVoid Void an order or an authorization Order Payment Action for Express Checkout An order payment action represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days To set up an order specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests PAYMENTREQUEST_nN_PAYMENTACTION Order An order enables you to create multiple authorizations over the 29 days each authorization you create places the buyer s funds on hold for up to three days You can capture multiple payments for each authorization up to 115 of or USD 75 more than the amount you specify in the DoExpressCheckoutPayment request NOTE The default number of child authorizations in your PayPal account is 1 To do multiple authorizations please contact PayPal to request an increase This payment action provides the most flexibility and should be used when either a sale does not meet or one authorization plus one reauthorization do not meet your needs Situations in which orders are appropriate include the handling of e Back orders in which available merchandise is sent immediately and the remaining merchandise is sent when available which may include more than two shipments e Split orders in which merchandise is sent in more than one shipment perhaps to different addresses and you want to
64. erver for use with API certificates NOTE You must use different API credentials for each server end point Typically you obtain API credentials when you test in the Sandbox and then obtain another set of credentials for the production server You must change each API request to use the new credentials when you go live Logging API Operations You should log basic information from the request and response messages of each PayPal API operation you execute You must log the Correlation ID from the response message which identifies the API operation to PayPal and which must be provided to Merchant Technical Support if you need their assistance with a specific transaction All responses to PayPal API operations contain information that may be useful for debugging purposes In addition to logging the Correlation ID from the response message you can log other information such as the transaction ID and timestamp to enable you to review a transaction on the PayPal website or through the API You could implement a scheme that logs the entire request and response in a verbose mode however you should never log the password from a request April 2012 PayPal Payments Pro Integration Guide Getting Started With the PayPal Name Value Pair API A Responding to an NVP Response Responding to an NVP Response The Name Value Pair response consists of the answer to the request as well as common fields that identify the API operation and ho
65. feedback to documentationfeedback Opaypal com 8 April 2012 PayPal Payments Pro Integration Guide Introducing PayPal Payments Pro You can accept credit and debit cards and PayPal payments directly on your website using 2 API based solutions Direct Payment and Express Checkout You must integrate with both Direct Payment and Express Checkout to use PayPal Payments Pro known as Website Payments Pro outside the U S e PayPal Payments Pro Overview e Additional Features of PayPal Payments Pro e PayPal Payments Pro API Operations e Website Payments Pro Regional Differences Getting Related Information All PayPal documentation is available on x com including video demos forums and developer resources e For information about administrative tasks you can perform from your PayPal account such as adding users setting up custom page styles and managing multiple currency balances see the Merchant Setup and Administration Guide e If you use the Payflow API to process transactions with PayPal as your internet merchant account see Gateway Developer Guide and Reference PayPal Payments Pro Overview PayPal Payments Pro includes Direct Payment Express Checkout and additional PayPal solutions and tools such as Virtual Terminal Fraud Management Filters and reference transactions e Direct Payment enables you to accept both debit and credit cards directly from your site e Express Checkout enables you to accept pa
66. g Recurring Payments EN Modifying a Recurring Payments Profile You can modify only the following specific information about an active or suspended profile e Subscriber name or address e Past due or outstanding amount e Whether to bill the outstanding amount with the next billing cycle e Maximum number of failed payments allowed e Profile description and reference e Number of additional billing cycles e Billing amount tax amount or shipping amount NOTE You cannot modify the billing frequency or billing period of a profile You can modify the number of billing cycles in the profile You can modify the following profile information during the trial period or regular payment period e Billing amount e Number of billing cycles NOTE For recurring payments with the Express Checkout API PayPal does not allow certain updates such as billing amount within 3 days of the scheduled billing date The profile changes take effect with the next payment after the call to update the profile Say for example the buyer has made 1 trial payment out of a total of 3 You call UpdateRecurringPayment sProfile to increase the number of billing cycles to 5 This provides the buyer with 4 additional trial payments If you call UpdateRecurringPaymentsProfile during the regular payment period the changes take effect with the buyer s next scheduled regular payment For complete details see the Name Value Pair Developer Guide and Reference or
67. hen you set up an Express Checkout transaction you specify values in the SetExpressCheckout request and then call the API The values you specify control the PayPal page flow and the options available to you and your buyers You should start by setting up a standard Express Checkout transaction which can be modified to include additional options To set up the simplest standard Express Checkout transaction 1 Specify that you want to execute the SetExpressCheckout API operation and the version you want to use PayPal Payments Pro Integration Guide April 2012 45 46 Getting Started With Express Checkout Implementing the Simplest Express Checkout Integration METHOD SetExpressCheckout VERSION XX 0 2 Specify your API credentials Use the following parameters for a signature USER API_usemame PwD API_password SIGNATURE APL signature In the Sandbox you can always use the following signature USER sdk three_apil sdk com PWD QF ZCWN5HZM8VBG7Q SIGNATURE A IzJh2ZZ jhg2 9XO2qnhapuwx1IDzyAZQ92FRP 5dqBzVesOkzbdUONzmOU 3 Specify the amount of the transaction include the currency if it is not in US dollars Specify the total amount of the transaction if it is known otherwise specify the subtotal Regardless of the specified currency the format must have a decimal point with exactly two digits to the right and an optional thousands separator to the left which must be a comma For example EUR 2 000 0
68. https developer paypal com before you log in to a Sandbox test account You then log in to the test account that represents the buyer not the seller s business test account that represents you as the merchant 4 After logging into the buyer test account confirm the details When you confirm the Sandbox redirects your browser to the return URL you specified when invoking the SetExpressCheckout API operation as in the following example PayPal Payments Pro Integration Guide April 2012 51 E Getting Started With Express Checkout Testing an Express Checkout Integration http www YourReturnURL com token EC 1NK66318YB717835M6PayerID 7AKUSARZ7SAT8 5 Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox lt form method post action https api 3t sandbox paypal com nvp lt input type hidden name USER value API_username gt lt input type hidden name PWD value API_passwora gt lt input type hidden name SIGNATURE value API_signature gt lt input type hidden name VERSION value XX 0 gt lt input name TOKEN value EC 1NK66318YB717835M gt lt input type submit name METHOD value GetExpressCheckoutDetails gt lt form gt Gl GS If the operation was successful the GetExpressCheckoutDetails API returns information about the payer such as the following information TIMESTAMP 2007 2d04 2d05T23 3a44 3a11Z amp CORRELATIONID
69. iar wary ta rer L HTTP Redirect mam aai 2 a S HTTP Redirect RetumURL Token EE Continuo 2 _ Receipt ms Request Token O e GetExpressCheckoutDetails PayPal Pay Now A _ Response Customer Details m Sandbox o Request Final Transaction Details sb alaa DoExpressCheckoutPayment PayPal Sandbox Goo Response Transaction Results semm Success Failure O The following steps match the circled numbers in the diagram Perform the actions in each step to test Express Checkout 1 Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox To invoke the API set form fields whose names match the NVP names of the fields you want to set specify their corresponding values and then post the form to a PayPal Sandbox server such as https api 3t sandbox paypal com nvp as shown in the following example 50 April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout EEN Testing an Express Checkout Integration lt form method post action https api 3t sandbox paypal com nvp gt lt input type hidden name USER value API_username gt lt input type hidden name PWD value API_passwora gt lt input type hidden name SIGNATURE value API_signature gt lt input type hidden name VERSION value XX 0 gt lt input type hidden name PAYMENTREQUEST_0_PAYMENTACTION value Sale gt lt input name PAYM
70. ific error These values are not set by PayPal rather they are passed through from the source NOTE PayPal only passes selected values in the L_ERRORPARAMIDn and L_ERRORPARAMVALUEn fields URL Decoding All responses to HTTP POST operations used by the PayPal NVP API must be decoded The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server You must decode all data returned using the HTTP protocol so that it can be displayed properly Most programming languages provide a way to decode strings 86 April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only Website Payments Pro allows UK merchants to pass 3 D Secure authentication data to PayPal for debit and credit cards processed with the DoDirectPayment API request Updating your site with 3 D Secure enables your participation in the Verified by Visa and MasterCard SecureCode programs NOTE A US or Canadian merchant can implement 3 D Secure however the authentication data is ignored by PayPal This information only applies to 3 D Secure for UK merchants implementing Direct Payment e Introduction to 3 D Secure e Integration Overview e Cardinal Commerce Registration and Installation e Transaction Processing e Website Setup e Examples e Testing e cmpi_lookup API e Issuer Authentication Fields e cmpi_authenticate API Introduction to 3 D Secure 3 D Secure is
71. in PayPal Inc reserves the right to make changes to any information herein without further notice Contents Preface 150 Lois al aa a a a e a A Intended Audience ee 7 Revision FISIO o sis oo be doth hbo de id we es A Pe ee Aen db oe amp 7 Where to Go for More Information 2 a a 8 Documentation Feedback 0000 ee ee 8 Chapter 1 Introducing PayPal Payments Pro 49 Getting Related Information e 9 PayPal Payments Pro OvervieW e 9 Additional Features of PayPal Payments Pro 0 o 10 Settlements and Captured Payments 0 0000 e o 11 Recurring Payments ass sasaa N R NK RRR KR KNN N 11 Virtual Terminal ee 11 Hosted Solution gt e ss aradt asa mad taa ieda d RRR R R R N 12 Fraud Management Filters oa a aa ee ee eee 12 Event Notification as esrara asarana ararau saranan 12 PayPal Payments Pro API Operations o oo aa eee ee ee 13 Website Payments Pro Regional Differences 0 0 o 15 Credit CardS s e e aa cc a a Ee ee ee R 15 Default Currency and Transaction Limits o 2 000005 eae 15 Credit Card Currencies by Country o o e 16 Addresses adi aoe i a a a a h a e ee 17 Chapter 2 Introducing Direct Payment 19 The Direct Payment User Experience 2 2 a 19 User Interface Recommendations for Direct Payment Chec
72. information about Fraud Management Filters see Fraud Management Filters Event Notification In most cases you can use the GetTransactionDetails API operation to determine the information you need about a transaction However there may be some cases in which you must set up IPN for example when you need automatic notification about actions such as disputes and their resolution IPN is a message service that PayPal uses to notify you about events such as e Instant payments including Express Checkout Adaptive Payments and direct credit card payments and authorizations which indicate a sale whose payment has not yet been collected April 2012 PayPal Payments Pro Integration Guide Introducing PayPal Payments Pro E PayPal Payments Pro API Operations e eCheck payments and associated status such as pending completed or denied and payments pending for other reasons such as those being reviewed for potential fraud e Recurring payment and subscription actions e Chargebacks disputes reversals and refunds associated with a transaction For more information about IPN see Instant Payment Notification Guide PayPal Payments Pro API Operations The PayPal API supports a range of functions related to payment processing Though most API operations support both Direct Payment and Express Checkout some are specific to Direct Payment and others are specific to Express Checkout PayPal API Operation Description Dire
73. ing Blocks 32 April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment To get started with Direct Payment implement and test the simplest DoDirectPayment API operation which is a sale Then you can expand your use of Direct Payment to include authorization and capture e Implementing the Simplest Direct Payment Integration e Testing Direct Payment Using NVP and cURL e Direct Payment Authorization and Captures Implementing the Simplest Direct Payment Integration To execute a direct payment transaction you must invoke the DoDirectPayment API operation with sufficient information to identify the buyer s credit or debit card and the amount of the transaction This example assumes that you have set up the mechanism you will use to communicate with the PayPal server and have a PayPal business account with API credentials It also assumes that the payment action is a final sale To set up the simplest direct payment transaction 1 Specify the amount of the transaction include the currency if it is not in US dollars Specify the total amount of the transaction if it is known otherwise specify the subtotal Regardless of the specified currency the format must have decimal point with exactly two digits to the right and an optional thousands separator to the left which must be a comma for example EUR 2 000 00 must be specified as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00
74. ing Express Checkout A generic flow probably has the following sequence of pages A generic checkout flow Shopping Cart Collect Shipping addresses In a typical checkout flow a buyer 1 Checks out from the shopping cart page 2 Provides shipping information 3 Chooses a payment option and provides billing and payment information 4 Reviews the order and pays 5 Receives an order confirmation In an Express Checkout flow a buyer still checks out at the beginning of the flow However the buyer does not enter shipping billing or payment information because PayPal provides the stored information This simplifies and expedites the checkout process The following diagram shows the Express Checkout flow PayPal Payments Pro Integration Guide April 2012 23 4 Introducing Express Checkout Express Checkout Integration Steps Express Checkout flow Legend Merchant Website ggg PayPal Website A m mmm A Checkout K K Confirmation mia gt gt Ad To Cart A D Pay Now Choose a way Review your Confirm order Order to pay information confirmation Dee safar rp wey gt pay Shopping cart In the Express Checkout flow the buyer 1 Chooses Express Checkout by clicking Check out with PayPal 2 Logs into PayPal to authenticate his or her identity 3 Reviews the transaction on PayPal NOTE Optionally not shown in the diagram the buyer can then proceed to review the order on your site You can also
75. ions Recurring payments IPN messages and email Event IPN Buyer Email Profile successfully created Yes Yes Profile creation failed Yes Yes Profile canceled from paypal com interface Yes Yes Profile status changed using API No Yes Profile updated using API No Yes Initial payment either succeeded or failed Yes Yes Payment either succeeded or failed during either trial Yes Yes period or regular payment period Outstanding payment either succeeded or failed Yes Yes Maximum number of failed payments reached Yes No NOTE API transactions such as ManangeRecurringPaymentsProfileStatus do not trigger IPN notification The API response immediately provides the success or failure of the call PayPal Payments Pro Integration Guide April 2012 73 6 Integrating Recurring Payments Recurring Payments Notifications 74 April 2012 PayPal Payments Pro Integration Guide Getting Started With the PayPal Name Value Pair API The PayPal Name Value Pair NVP API provides parameter based association between request and response fields of a message and their values The request message is sent via the API from your website and a response message is returned by PayPal using a client server model in which your site is a client of the PayPal server NOTE The PayFlow API also uses name value pairs to provide parameter based association between request and response fields of a message and their values however the PayFlow API is not the same as the
76. ir API PayPal API Client Server Architecture PayPal Name Value Pair API Requests and Responses To perform a PayPal NVP API operation you send an NVP formatted request to a PayPal NVP server and interpret the response In the following diagram your website generates a request The request is executed on a PayPal server and the response is returned to your site Your Site i Request API operation ooo gt API credentials gt Checkout Request specific fields ames U PayPal NVP Response API Server p de Acknowledgement status de Ta eatery toon Tracking information i Response specific fields The request identifies e The name of the API operation specified by METHOD name to be performed and its version NOTE After the METHOD parameter you can specify the parameters in any order e Credentials that identify the PayPal account making the request e Request specific information that controls the API operation to be performed A PayPal API server performs the operation and returns a response The response contains e An acknowledgement status that indicates whether the operation was a success or failure and whether any warning messages were returned e Information that can be used by PayPal to track execution of the API operation e Response specific information required to fulfill the request UTF 8 Character Encoding The PayPal API assumes that all data in requests is in Unicode specifically the Unicode or
77. irtual Terminal Users Guide Hosted Solution Hosted Solution which is available to merchants in the United Kingdom as part of PayPal Payments Pro is a fast and easy way to add transaction processing to your website It is a secure PayPal hosted web based payment solution that allows you to securely send your buyers to PayPal s payment page to authorize and process transactions Buyers pay with a debit or credit card or their PayPal account You do not have to capture or store credit card information on your website thereby helping towards achieving PCI compliance Hosted Solution is the choice for merchants who prefer a solution where all financial details are handled by PayPal For more information about Hosted Solution for UK merchants see Website Payments Pro Hosted Solution Integration Guide Fraud Management Filters Fraud Management Filters FMF provide you filters that identify potentially fraudulent transactions There are 2 categories of filters e Basic filters screen against data such as the country of origin and the value of transactions PayPal provides basic filters for Business accounts and Website Payments Pro accounts e Advanced filters screen data such as credit card and addresses information lists of high risk indicators and additional transaction characteristics Website Payments Pro merchants can upgrade to use these filters NOTE Using advanced filters might incur additional charges For more
78. it or debit card during your checkout flow You have complete control over the experience however you must consider PCI compliance When buyers choose to pay with a credit or debit card they enter their card number and other information on your website After they confirm their order and click Pay you complete the order in the background by invoking the DoDirectPayment API operation Buyers never leave your site Although PayPal processes the order buyers aren t aware of PayPal s involvement PayPal will not even appear on the buyer s credit card statement for the transaction The following diagram shows a typical Direct Payment flow Your Website Shopping Cart Shipping Info Billing Info Order Review Order Complete O Vis Paye py 1 2 4 O PayPal vl L gt gt Thank You CHECKOUT CONTINUE COMTIMUE Pay C T EE PayPal Web Services The numbers in the diagram correspond to the following implementation steps 1 On your checkout pages you need to collect the following information from a buyer to be used in the DoDirectPayment request Amount of the transaction Credit card type Credit card number Credit card expiration date PayPal Payments Pro Integration Guide April 2012 19 i Introducing Direct Payment The Direct Payment User Experience Credit card CSC value Cardholder first and last name Cardholder billing address The following example shows the collection
79. kout 21 Chapter 3 Introducing Express Checkout 423 The Express Checkout Experience oaoa o 23 Express Checkout Integration Steps 2 2 4 24 Configuring and Customizing the Express Checkout Experience 25 Additional PayPal API Operations 0 a 25 PayPal Payments Pro Integration Guide April 2012 EN Contents Express Checkout Flow 26 Checkout Entry Point aoaaa 26 Payment Option Entry Point 2 0 eo 27 Express Checkout Building Blocks o e eo eo o 27 PayPal Button and Logo Images o 28 Express Checkout API Operations 00000 eee eee 30 Express Checkout Command 0002 eee ee es 30 Express Checkout Token Usage 2 2 a o 31 Chapter 4 Getting Started With Direct Payment 33 Implementing the Simplest Direct Payment Integration 2 4 33 Testing Direct Payment Using NVP and cURL 02000 34 Direct Payment Authorization and Captures 00 0200022 e 38 Sale Payment Action for Direct Payment 200000000 e 38 Authorization and Capture for Direct Payment 0 38 DoDirectPayment Authorization and Capture Example 39 DoDirectPayment Reauthorization and Capture Example 41 Chapter 5 Getting Started With Express Checkout 45 Implementing the Simplest Express Ch
80. koutDetails API operation and the version you want to use METHOD GetExpressCheckoutDetails VERSION XX 0 PayPal Payments Pro Integration Guide April 2012 47 E Getting Started With Express Ch Implementing the Simplest Express Ch eckout eckout Integration 2 Specify your API credentials Use the following parameters for a signature USER API_usemame PWD API_password SIGNATURE API_signature 3 Specify the token returned by PayPal when it redirects the buyer s browser to your site PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified i TOKEN fokenValue n your call to the SetExpressCheckout API 4 Execute the GetExpressCheckoutDetails API to obtain information about the buyer 5 Access the fields in the NOTE Only populated GetExpressCheckoutDetails API response fields are returned in the response Completing the Express Checkout Transaction To complete an Express Checkout transaction you must invoke the DoExpressCheckoutPayment API operation This example assumes that PayPal redirects your buyer s browser to your website with a valid token after you call the SetExpressCheckout API Optionally you may call the GetExpressCheckoutDetails API before calling the DoExpressCheckoutPayment API In the simplest case you set the total amount of the order when you call the SetExpressCheckout A PI Howe
81. lect the most current Cardinal information PayPal Payments Pro Integration Guide April 2012 89 B Implementing 3 D Secure Transactions UK Only Transaction Processing URL to Handle Issuer s Response You must establish a page on your site whose URL can receive a form POST from the card s issuer that contains two fields PaRes and MD The page must then request cmpi_authenticate as described in the next section Your page s URL is referred to as TermURL Transaction Flow NOTE The steps in this section are explained in the Cardinal Thin Client Integration Guide Payer Authentication document refer there for the most current information This summary is provided for you as a convenience Transaction flow with numbered steps To create a 3 D Secure transaction using Website Payments Pro and Cardinal Centinel do the following before executing the direct payment request 1 Call Cardinal Centinel with the cmpi_lookup request passing your merchant and transaction information See cmpi_lookup API for the complete list of required fields 2 The cmpi_lookup request responds with several fields see cmpi_lookup API for details about these fields 90 April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only Transaction Processing Error information Evaluate and take appropriate action if nonzero Refer to the Thin Client Integration Guide for error codes descriptions expl
82. lled Y this contains the encoded transaction details otherwise this field is empty EciFlag The Electronic Commerce Indicator ECI MasterCard e 01 Merchant Liability e 02 Issuer Liability Visa e 05 Issuer Liability e 06 Issuer Liability e 07 Merchant Liability Issuer Authentication Fields The call to the card issuer s site is explained in the Cardinal Thin Client Integration Guide Payer Authentication document This section lists required fields and responses as a convenience Issuer Authentication Request Specify the following fields when you call the card issuer s URL that you received from cmpi_lookup in ACSUr1 Issuer Authentication Request Fields Field Description PaReg Required Content of the Payload field from cmpi_lookup TermUrl Required Your URL for handling and processing the response from the ACSUrl Required Merchant s session tracker Set to blank if not used PayPal Payments Pro Integration Guide April 2012 97 B Implementing 3 D Secure Transactions UK Only cmpi_authenticate API Issuer Authentication Response When the issuer has completed its authentication processing it calls the URL that you provided to it in TermURL The issuer returns the following fields Issuer Authentication Response Fields Field Description PaRes Authentication information to pass to cmpi_authenticate Copy of MD sent by merchant cmpi_authentica
83. ment action in the DoDirectPayment request because the goods might not ship at the same time For each of these items you call DoCapture to collect the payment On the first day you ship the first item and on the third day you ship the second item The payments for these items succeed because they occur within the honor period If you ship the third item on the fifth day your call to DoCapture might fail if the issuer declined the attempt by PayPal to reauthorize Because the honor period has expired you should explicitly call DoReauthorization before calling DoCapture to determine whether the buyer s funds are still available Likewise if all three items were to be shipped together after the honor period but before the valid period expires you should explicitly call DoOReauthorization before calling DoCapture When you call DoCapture for the final payment you must set the COMPLETETYPE field to Complete Prior calls to DoCapture must set this field to NotComplete When payments are complete any remaining uncaptured amount of the original authorization is automatically voided and nothing more can be captured You can explicitly void an authorization in which case the uncaptured part of the amount specified in the DoDirectPayment request becomes void and can no longer be captured If no part of the payment has been captured the entire payment becomes void and nothing can be captured For Visa and MasterCard a hold caused by
84. ments Pro You can then use the account to test credit and debit card payments using the DoDirectPayment API operation You can then simulate debit or credit card payments from cards that exist in the Sandbox This example shows how to simulate a DoDirectPayment API operation using cURL to supply the NVP request values and to call DoDirectPayment To test Direct Payment in the Sandbox you must first ensure that the Sandbox test account is associated with a credit card and enabled for Website Payments Pro The following example uses the cur1 command to execute the DoDirectPayment request and obtain a response You can use the strategy shown in these steps for initial testing of your Direct Payment implementation For more complete testing you should integrate cURL into your checkout pages April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL The following steps show how you can test the DoDirectPayment API operation 1 Execute the DoDirectPayment API operation to complete the transaction The following example uses cURL to communicate with PayPal A curl insecure https api 3t sandbox paypal com nvp d VERSION 56 0 amp SIGNATURE api_signature amp USER api_username amp PWD api_password amp METHOD DoDirectPayment amp PAYMENTACTION Sale amp IPADDRESS 192 168 0 1 amp AMT 8 88 amp CREDITCARDTYPE Visa amp ACCT 46830754105166
85. n More Payment Type instant Surcharges Not Applicable Card Type Visa Address Verification x Service AVS Card Security Code CSC M PayPal Payments Pro Integration Guide April 2012 37 38 Getting Started With Direct Payment Direct Payment Authorization and Captures Direct Payment Authorization and Captures You can use PayPal API operations to handle the capture of payments authorized using DoDirectPayment e Sale Payment Action for Direct Payment e Authorization and Capture for Direct Payment s DoDirectPayment Authorization and Capture Example e DoDirectPayment Reauthorization and Capture Example Sale Payment Action for Direct Payment A sale payment action represents a single payment that completes a purchase for a specified amount A sale is the default payment action however you can also specify the action in your DoDirectPayment requests PAYMENTACTION Sale A sale is the most straightforward payment action Choose this payment action if the transaction including shipping of goods can be completed immediately Use this payment action when you intend to fulfill the order immediately such as would be the case for digital goods or for items you have in stock for immediate shipment After you execute the DoDirectPayment API operation the payment is complete and further action is unnecessary You cannot capture a further payment or void any part of the payment when you use this payment action Authori
86. nform buyers that PayPal is accepted on your website you must place PayPal button and logo images in your checkout flow PayPal recommends that you use dynamic images PayPal requires that you use Check out with PayPal buttons and PayPal mark images hosted on secure PayPal servers When the images are updated the changes appear automatically in your application Do not host copies of the PayPal images locally on your servers Outdated PayPal buttons and images reduce buyer confidence in your site Express Checkout Image Flavors The Check out with PayPal button and the PayPal mark image are available in two flavors e Dynamic image e Static image The dynamic images enable PayPal to change their appearance dynamically If for example you have signed up to participate in a PayPal campaign PayPal can change the appearance of the image dynamically for the duration of that campaign based on parameter information you append to the image URL The static images cannot be changed dynamically To participate in a PayPal campaign you would have to manually update the image code to change the image displayed and restore the default image when the campaign is over The only way you can have image management taken care of for you is to replace static images in your implementation with dynamic images April 2012 PayPal Payments Pro Integration Guide Introducing Express Checkout PU Express Checkout Building Blocks Express Checkout Images The Che
87. ng payments profile NOTE You can also bill the buyer for the current past due or outstanding amount for a recurring payments profile from the PayPal website To bill the outstanding amount e The profile status must be active or suspended NOTE The BillOutstandingAmount API does not reactivate a suspended profile You need to call ManageRecurringProfileStatus to do this e The profile must have a non zero outstanding balance e The amount of the payment cannot exceed the outstanding amount for the profile e The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile NOTE An error occurs when another outstanding balance payment is already queued PayPal informs you by IPN about the success or failure of the outstanding payment For profiles created using Express Checkout the buyer receives an email notification of the payment Recurring Payments Notifications PayPal notifies you of recurring payments events through IPN and email Typically however you can call GetTransactionDetails to obtain the information you need PayPal notifies you of certain events through IPN For recurring payments profiles created using Express Checkout PayPal also notifies buyers of specific events by email The following table indicates when PayPal generates IPN and emails April 2012 PayPal Payments Pro Integration Guide Integrating Recurring Payments EN Recurring Payments Notificat
88. nly Examples Examples The following examples outline the transaction process for three basic situations Example 1 Successful 3 D Secure Authentication In this example the cardholder s issuer uses 3 D Secure and the authentication is successful 1 2 Construct your message for cmpi_lookup Review the response from cmpi_lookup Ensure that all of the following are true ErrorNo 0 Enrolled Y ACSUrl has content for example lt ACSUrl gt https www somewebsite com acs lt ACSUrl gt Using HTTP Form POST redirect the cardholder to the issuer s URL that was provided in ACSUr1 Ensure that the PaReq has the data from the field PayLoad from the cmpi_lookup response Send the response redirect from the issuer s HTTP Form POST to Cardinal using the cmpi_authenticate message to determine how to proceed with the transaction The cmpi_authenticate response will specify how to proceed To continue with authorization the following must be true SignatureVerification Y PAResStatus Y U or A Authoress as normal with the additional fields described in 3 D Secure Fields for Direct Payment Transaction Requests Example 2 3 D Secure with Unsuccessful Authentication In this example the cardholder s issuer uses 3 D Secure and the authentication is not successful 1 Construct your message for cmpi_lookup 2 Review the response from cmpi_lookup Ensure that
89. nt TRIALTOTALBILLINGCYCLES ScheduleDetails TrialPeriod TotalBillingCycles Specifying an Initial Payment You can optionally specify an initial non recurring payment when the recurring payments profile is created by including the following fields in the CreateRecurringPaymentsProfile request Required fields for specifying an initial payment NVP SOAP INITAMT ScheduleDetails ActivationDetails InitialAmount FAILEDINITAMTACTION ScheduleDetails ActivationDetails FailedInitAmountAction By default PayPal does not activate the profile if the initial payment amount fails To override this default behavior set the FAILEDINITAMTACTION field to ContinueOnFailure If the initial payment amount fails Cont inueOnFailure instructs PayPal to add the failed payment amount to the outstanding balance due on this recurring payment profile If you do not set FATLEDINITAMTACTION or set it to CancelOnFailure PayPal creates the recurring payment profile However PayPal places the profile into a pending status until the initial payment completes If the initial payment clears PayPal notifies you by Instant Payment Notification IPN that it has activated the pending profile If the payment fails PayPal notifies you by IPN that it has canceled the pending profile If you created the profile using Express Checkout the buyer receives an email stating that PayPal cleared th
90. nts Pro Integration Guide Getting Started With the PayPal Name Value Pair API oa Creating an NVP Request should consistently URL encode the complete API request otherwise you may find that unanticipated data causes an error NOTE An HTTP form is automatically URL encoded by most browsers For example consider the following NVP string NAME Robert Moore amp COMPANY R H Moore amp Associates It is encoded as follows NAME Robert Moore amp COMPANY R 2E H 2E Moore 26 Associates Use the following methods to URL encode or URL decode your NVP strings Encoding and decoding methods for URLs Language Method ASP NET Encode System Web HttpUtility UrlEncode buffer Encoding Default Decode System Web HttpUtility UrlDecode buffer Encoding Default Classic ASP Encode Server URLEncode Decode No built in function Several implementation examples are available on the Internet Java Encode java net URLEncoder encode Decode java net URLDecoder decod PHP Encode urlencode Decode urldecode ColdFusion Encode URLEncodedFormatstring charset Decode URLDecodeurlEncodedString charset List Syntax for Name Value Pairs The PayPal API uses a special syntax for NVP fields defined as lists The NVP interface to the PayPal API requires a unique name for each field In the API lists are prefixed by L_ To identify an element within the list use the
91. o protection e U Unable to complete no protection e A Successful merchant is protected Cavv A random sequence of characters this is the encoded authentication SignatureVerification Status of authentication eligibility If not Y then the cardholder is not eligible for authentication Possible values are e Y Good e N Bad EciFlag The Electronic Commerce Indicator ECI MasterCard e 01 Merchant Liability e 02 Issuer Liability Visa e 05 Issuer Liability e 06 Issuer Liability e 07 Merchant Liability Xid Transaction identifier from authentication PayPal Payments Pro Integration Guide April 2012 99 B Implementing 3 D Secure Transactions UK Only cmpi_authenticate API 100 April 2012 PayPal Payments Pro Integration Guide
92. offset from the beginning of the list starting with O as the first element For example L_ DESCO is the first line of a description L_DESC1 is the second line and so on NOTE Not all lists follow the L_ prefix convention however all lists start with O as the first element PayPal Payments Pro Integration Guide April 2012 83 84 Getting Started With the PayPal Name Value Pair API Executing NVP API Operations Executing NVP API Operations You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal API server or by using cURL or another mechanism to provide secure access between the buyer s browser and the PayPal API server For example you might implement a system in which the buyer s browser remains a client of your server and your server becomes a client of the PayPal API server Specifying a PayPal Server You execute a PayPal API operation by submitting the request to a PayPal API server To execute a PayPal NVP API operation submit the request to one of the following end points Server end point Description https api Sandbox server for use with API signatures use for testing your 3t sandbox paypal com nvp API https api 3t paypal com nvp PayPal live production server for use with API signatures https api sandbox paypal com nvp Sandbox server for use with API certificates use for testing your API https api paypal com nvp PayPal live production s
93. ofileDetails ManageRecurringPaymentsProfileStatus BillOutstandingAmount UpdateRecurringPaymentsProfile DoReferenceTransaction Reauthorize a previously authorized payment Void an order or an authorization Create a recurring payments profile Obtain information about a recurring payments profile Cancel suspend or reactivate a recurring payments profile Bill the buyer for the outstanding balance associated with a recurring payments profile Update a recurring payments profile Process a payment from a buyer s account which is identified by a previous transaction Recurring Payment Billing Agreement API operations Express Checkout only BAUpdate GetBillingAgreementCustomerDetails SetCustomerBillingAgreement Update or delete a billing agreement Obtain information about a billing agreement s PayPal account holder Initiates the creation of a billing agreement Other Express Checkout API operations Express Checkout only AddressVerify Callback GetBalance GetPalDetails MassPay Confirms whether a postal address and postal code match those of the specified PayPal account holder Express Checkout only Define the shipping and handling parameters associated with Express Checkout Obtain the available balance for a PayPal account Express Checkout only Obtain your Pal ID which is the PayPal assigned merchant account number and other information about your account
94. paypal business co uk 3Dsecure asp After you have registered Cardinal Commerce acknowledges your 3 D Secure registration by sending you an email and welcome pack which includes information about next steps and links for downloading their documentation and software Download and install the Cardinal Centinel Thin Client software Refer to the Cardinal documentation for installation instructions April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only Transaction Processing NOTE Cardinal Commerce will be available to schedule an integration meeting with you and will support you with your Cardinal Centinel Integration requirements PayPal page for Cardinal Commerce merchant registration PayPal Merchant Details y United Kingdom F Additional information PayPal imegration Transaction Processing Integrating Cardinal Centinel and 3 D Secure with your PayPal transaction processing is fairly straightforward You need to set up a web page that can handle a return call from the card s issuer insert three additional requests into your application before the direct payment request and add 3 D Secure payer authentication fields to the DoDirectPayment request NOTE Refer to the Cardinal documentation for the most recent Cardinal Centinel information Cardinal requests responses and processes are provided for you in this document as a convenience but might not ref
95. ready reached the maximum number of failed payments however you must increase the number of failed payments before reactivating the profile NOTE You can also suspend cancel or reactive a recurring payments profile through the PayPal website For recurring payments profiles created with the Express Checkout API the buyer receives an email about the change in status of their recurring payment Getting Recurring Payments Profile Information Use the GetRecurringPaymentsProfileDetails API to obtain information about a profile NOTE You can also get information about recurring payments profiles from the PayPal website Along with the information that you specified in the CreateRecurringPaymentsProfile request GetRecurringPaymentsProfileDetails also returns the following summary information about the profile e Profile status e Next scheduled billing date e Number of billing cycles completed in the active subscription period e Number of billing cycles remaining in the active subscription period e Current outstanding balance e Total number of failed billing cycles e Date of the last successful payment received e Amount of the last successful payment received Modifying a Recurring Payments Profile Use the UpdateRecurringPaymentsProfile API to modify a recurring payments profile NOTE You can also modify recurring payments profiles from the PayPal website April 2012 PayPal Payments Pro Integration Guide Integratin
96. reated by a capture of a payment The transaction is identified by a transaction ID that PayPal assigns when the payment is captured NOTE You cannot make a refund if the transaction occurred after the refund period has passed typically the refund period is 60 days You can refund amounts up to the total amount of the original transaction If you specify a full refund the entire amount is refunded If you specify a partial refund you must specify the amount to refund the currency and a description of the refund which is called a memo When you call the RefundTransaction API PayPal responds with another transaction ID which is associated with the refund not the original transaction and additional information about the refund This information identifies e The gross amount of the refund which is returned to the payer e The amount of the refund associated with the original transaction fee which is returned to you e The net amount of the refund which is deducted from your balance To issue a refund 1 In the RefundTransaction request specify the transaction ID of the transaction whose payment you want to refund TRANSACTIONID transaction_id 2 Specify the kind of refund which is either Full or Partial REFUNDTYPE Full or REFUNDTYPE Partial 3 For a partial refund specify the refund amount including the currency April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout CE
97. s Checkout API operations which guides a buyer through the checkout process You implement the Direct Payment flow using your own code for which PayPal provides an API operation to process the credit or debit card payment NOTE Purchases through Direct Payment are not covered by the PayPal Seller Protection Policy Additional Features of PayPal Payments Pro PayPal Payments Pro consists of APIs for accepting credit card debit card and PayPal payments these payments can be immediate authorized for later capture and they can be recurring payments PayPal Payments Pro also includes standalone applications for accepting payments In addition PayPal Payments Pro includes Fraud Management Filters for automatic review and management of risk 10 April 2012 PayPal Payments Pro Integration Guide Introducing PayPal Payments Pro A Additional Features of PayPal Payments Pro Settlements and Captured Payments Often you accept a payment and ship goods immediately which is refered to as sale In addition to immediate payments Direct Payment and Express Checkout both allow you to authorize payments to be captured later which is referred to as an authorization An authorization is useful for example when you want to reserve a buyer s funds pending the shipment of goods the actual payment is captured when the goods are shipped An authorization can be reauthorized one time if necessary for example when you are unable to ship within 3 da
98. se the appropriate version In most cases you should use the latest version of the API operation VERS ION version_number Specifying an API Credential You must specify API credentials in each request to execute a PayPal API operation When you execute a PayPal API operation you use credentials such as a signature to authenticate that you are requesting the API operation The following diagram shows the API credentials part of an NVP request Your Site l r NVP Request Checkout API operation i Ea USER sdk three_api1 sdk com gt PayPal PWO QFZCWN5HZM8VBG7Q API Server i SIGNATURE A IzJhZZjhg29 Request specific fields The vie amadas meg K rer IMPORTANT You must protect the values for USER PWD and SIGNATURE in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it PayPal Payments Pro Integration Guide April 2012 81 82 Getting Started With the PayPal Name Value Pair API Creating an NVP Request To enable PayPal to authenticate your request 1 Specify the API username associated with your account USER API_usemame 2 Specify the password associated with the API username PWD API_password 3 If you are using an API signature and not an API certificate specify the API signature associated with the API usernam
99. should display a message on the order confirmation page Otherwise you should show the buyer information related to the error You should also provide an opportunity to pay using a different payment method User Interface Recommendations for Direct Payment Checkout Your checkout pages must collect all the information you need to create the DoDi rectPayment request The request information can be collected by your site s checkout pages The following recommendations help process requests correctly and make it easier for buyers to provide necessary information IMPORTANT You are responsible for processing card industry PCI compliance for protecting cardholder data For example storing the Card Security Code CSC violates PCI compliance For more information about PCI compliance see PCI Security Standards Council e Provide a drop down menu for the state or province fields for addresses in countries that use them For U S addresses the state must be a valid 2 letter abbreviation for the state military location or U S territory For Canada the province must be a valid 2 letter province abbreviation For the UK do not use a drop down menu however you may need to provide a value for the state in your DoDirectPayment request e Ensure buyers can enter the correct number of digits for the Card Security Code CSC The value is 3 digits for Visa MasterCard and Discover The value is 4 digits for American Express e Sho
100. sing the NVP and SOAP API including use with airlines Added new Immediate Payment functionality Updated billing agreements with functionality to obtain the latest billing address skip billing agreement creation and clarify use of the BAUpdate API 03 10 10 Consolidated all regions US UK and Canada into one manual Added additional information about Direct Payment 10 05 09 Added Immediate Payment Edited for technical accuracy Removed PayPal placement guidelines 06 30 09 Added a section on payment review PayPal Payments Pro Integration Guide April 2012 a Where to Go for More Information Date Description 06 04 09 Added a chapter on pre populating the PayPal review page Updated PayPal Review pages Moved some customization topics out of this guide They are now in the Merchant Setup and Administration Guide 04 08 09 Added a chapter describing the Instant Update Callback API Added Express Checkout feature of passing AMT 0 to create one or more billing agreements 12 11 08 Revised the Website Payments Pro introduction and overview chapters 11 13 08 Added information about integrating dynamic images and added information about order details that can be displayed on the PayPal Review page 06 30 08 Complete revision Where to Go for More Information e Express Checkout Advanced Features Guide e Merchant Setup and Administration Guide Documentation Feedback Help us improve this guide by sending
101. ssCheckoutDetails The GetExpressCheckoutDetails method returns information about the buyer including name and email address stored on PayPal You can optionally call this API after PayPal redirects the buyer s browser to the ReturnURL you specified in the SetExpressCheckout request The GetExpressCheckout Details request has one required parameter TOKEN which is the value returned in the SetExpressCheckout response PayPal does not return the values you specified for the following parameter fields in the GetExpressCheckoutDet ails response unless the transaction includes a purchase PayPal ignores the fields if you set up a billing agreement for a recurring payment that is not immediately charged e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_ CUSTOM e PAYMENTREQUEST_n_INVNUM Creating the Profiles With CreateRecurringPaymentsProfile After your buyer has agreed to the recurring payments billing agreement on your confirmation page you must call CreateRecurringPaymentsProfile to create the profile If you are creating multiple recurring payments profiles you must call CreateRecurringPaymentsProfile once for each profile you plan to create If the transaction includes a mixture of a one time purchase and recurring payments profiles call DoExpressCheckout Payment to complete the one time purchase transaction Then call CreateRecurringPayment sProfile for each recurring payment profile you plan to create
102. t configuration or administration screen For building custom shopping carts Store the following credential information in a secure location with limited access Credential API Signature API Username gemccu_1229982509_biz_api1 cs com API Password QR9WVHAD2PYGC2P9 Signature AcmkMJg6sUeVPkIN3p qhvX 3 8A5HgZFIKWw EhLZBOKPuifytf06T RequestDate May 30 2011 22 43 04 PDT Done Remove 6 Click Done to complete the process 78 April 2012 PayPal Payments Pro Integration Guide Getting Started With the PayPal Name Value Pair API onl Obtaining API Credentials Creating an API Certificate Create an API certificate only if your website requires it Typically you want to create an API signature for your credentials instead You must have a PayPal Business account to create an API certificate NOTE The certificate for API credentials is not the same as an SSL certificate for your website they are not related to each other If you do need a certificate follow these instructions 1 Log in to PayPal then click Profile under My Account 2 Click My selling tools 3 Click API Access 4 Click Request API Credentials 5 Check Request API certificate and click Agree and Submit bs My Account Send Money Request Money Merchant Services Products amp Services Community Overview Add Funds Withdraw History Resolution Center Profile Virtual Terminal Download or Remove API Certificate Back to Profile Summary y Developers Do
103. t input type hidden name SIGNATURE value gt lt input type hidden name VERSION value 58 0 gt lt input type hidden name PAYMENTACTION value Authorization gt lt input type hidden name CREDITCARDTYPE value Visa gt lt input type hidden name ACCT value gt lt input type hidden name STARTDATE value 112000 gt lt input type hidden name EXPDATE value 112020 gt lt input type hidden name CVV2 value 123 gt lt input type hidden name AMT value 500 gt lt input type hidden name CURRENCYCODE value USD gt lt input type hidden name FIRSTNAME value gt lt input type hidden name LASTNAME value gt lt input type hidden name STREET value gt lt input type hidden name STREET2 value gt lt input type hidden name CITY value San Francisco gt lt input type hidden name STATE value CA gt lt input type hidden name Zip value 94121 gt lt input type hidden name COUNTRYCODE value US gt lt input type hidden name EMAIL value gt lt input type submit name METHOD value DoDirectPayment gt lt form gt If the authorization was successful the response contains the authorization ID in the transaction ID field TIMESTAMP 2010 2d03 2d05T03 3a55 3a13Z amp CORRELAT IONID 2 8b1e854 98 3e amp ACK Succ ess amp VERSION 62 2e0 amp BUILD 1218643 amp AMT 500 2e00 amp CURRENCY CODE USD amp AVSCODE X amp CV V2MATCH M8 TRANSACT IONID 4HS1916972552122T Use the transaction ID in the DoRea
104. t payment action is a Sale it is a best practice to explicitly specify the payment action as one of the following values PAYMENTREQUEST_0_PAYMENTACTION Sale After Completing This Task If calling the SetExpressCheckout API was successful redirect the buyer s browser to PayPal and execute the _express checkout command using the token returned in the SetExpressCheckout response NOTE The following example uses the PayPal Sandbox server https www sandbox paypal com webscr cmd _express checkout amp token lokenValue Obtaining Express Checkout Transaction Details To obtain details about an Express Checkout transaction you can invoke the GetExpressCheckoutDetails API operation This example assumes that PayPal redirects to your buyer s browser with a valid token after the buyer reviews the transaction on PayPal Although you are not required to invoke the GetExpressCheckoutDetails API operation most Express Checkout implementations take this action to obtain information about the buyer You invoke the GetExpressCheckoutDetails API operation from the page specified by return URL which you set in your call to the SetExpressCheckout API Typically you invoke this operation as soon as the redirect occurs and use the information in the response to populate your review page To obtain a buyer s shipping address and Payer ID 1 Specify that you want to execute the GetExpressChec
105. te API The cmpi_authenticate request is a Cardinal Centinel request This section lists required fields as a convenience for you Refer to the Cardinal Thin Client Integration Guide Payer Authentication document for details and the most current information cmpi_authenticate Request cmpi_authenticate Request Fields Field Description MsgType Required Must be cmpi_authenticate Version Required Must be 1 7 Processorld Required Your Processor identification code as assigned by Cardinal Merchant Id Required Your merchant identification code as assigned by Cardinal TransactionPwd Required Your Cardinal password as you configured it at the Cardinal site TransactionType Required Must be C TransactionId Required The transaction identifier returned from cmpi_lookup PAResPayload Required PaRes provided in the package returned after the call to the card s issuer cmpi_authenticate Response cmpi_authenticate Response Fields Field Description ErrorNo Error number 0 indicates no error 1140 indicates that the cardholder pressed Back 98 April 2012 PayPal Payments Pro Integration Guide Implementing 3 D Secure Transactions UK Only Boo cmpi_authenticate API Field Description ErrDesc Empty if there is no error otherwise describes the error PAResStatus The outcome of the issuer s authentication Possible values are e Y Successful merchant is protected e N Failed n
106. tegration Guide April 2012 29 4 Introducing Express Checkout Express Checkout Building Blocks To create a PayPal mark see https www paypal com cgi bin webscr cmd xpt Marketing general OnlineLogoCenter outside Express Checkout API Operations The PayPal API provides three API operations for Express Checkout These API operations set up the transaction obtain information about the buyer and handle the payment and completes the transaction API Operation Description SetExpressCheckout Sets up the Express Checkout transaction You can specify information to customize the look and feel of the PayPal site and the information it displays You must include the following information e URL to the page on your website that PayPal redirects to after the buyer logs into PayPal and approves the payment successfully URL to the page on your website that PayPal redirects to if the buyer cancels Total amount of the order or your best estimate of the total It should be as accurate as possible GetExpressCheckout Obtains information about the buyer from PayPal including shipping information DoExpressCheckout Payment Completes the Express Checkout transaction including the actual total amount of the order Express Checkout Command 30 PayPal provides a command that you use when redirecting your buyer s browser to PayPal This command enables your buyer to log in to PayPal to approve an Express Checkout paym
107. tinue to process transactions without authentication If you use either of these features in your current integration you must exclude the Maestro card type from the available options NOTE Merchants must register with Cardinal Commerce before using this feature For more information see Verified by Visa http www visaeurope com personal onlineshopping verifiedbyvisa main jsp MasterCard SecureCode http www mastercard com us merchant solutions mastercard_securecode html Cardinal Centinel http www paypal business co uk 3Dsecure asp Integration Overview To use 3 D Secure with PayPal you must do the following Each item is explained in detail later in this document Register your company with Cardinal Commerce and download and install the Cardinal Thin Client package Insert processing for 3 D Secure into your application s debit or credit card payment flow immediately before the direct payment API request Add additional fields to the direct payment API request Update your website with required 3 D Secure logos status windows and other information for your customers Test your 3 D Secure integration using Cardinal s testing facilities PayPal s Sandbox cannot be used for testing 3 D Secure functionality Cardinal Commerce Registration and Installation Before you can use Cardinal Centinel to obtain cardholder authentication 1 Register with Cardinal by filling in a simple form http www
108. urring payments April 2012 63 64 Integrating Recurring Payments Recurring Payments With the Express Checkout API e Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one time purchase or recurring payment NOTE You can also initiate the processing flow using SetCustomerBillingAgreement for orders that contain only a single recurring payment Typically you set the amount of the payment for an Express Checkout transaction when you call the SetExpressCheckout request You confirm the amount in the DoExpressCheckoutPayment request If however you set the amount of the payment to 0 in the SetExpressCheckout request you can create a billing agreement without initiating a payment NOTE Tocreate a billing agreement without purchase use Version 54 0 or higher of the PayPal API To set up one or more billing agreements for recurring payments modify the SetExpressCheckout request as follows 1 Add an L_BILLINGTYPEn field for each billing agreement you want to create n is a value in the range of 0 to 9 inclusive Set the value of each field to RecurringPayments L_BILLINGTYPEO RecurringPayments 2 Add an L_BILLINGAGREEMENTDESCRIPTIONn field to correspond to each L_BILLINGTYPEn field you pass n is a value in the range of 0 to 9 inclusive Set the value of each field to the description of the goods or services associated with that billing
109. us Verified Last log in ProSel_1267046863_ PayPal balance 8 27 USD My recent activity Payments received Payments sent View all of my transactions My recent activity Last 7 days Feb 18 2010 Feb 25 2010 Archive What s this Payment status glossary FT Date Type Name Email Payment status Details Order status Actions Gross P Feb25 2010 PaymentFrom TestUser Completed Details 8 88 USD Archive What s this About Us Contact Us Legal Agreements Privacy Fees Site Feedback H Copyright 1999 2010 PayPal All rights reserved Information about FDIC pass through insurance Test Site 36 April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment a Testing Direct Payment Using NVP and cURL 4 Click the Details link to see the status of the transaction Web Accept Payment Received Unique Transaction ID 4067224976738143V Name TestUser The sender ofthis paymentis Unregistered Email No email address included Payment Sent to ProSel_1267046868_biz live com Total Amount 8 88 USD Fee amount 50 61 USD Net amount 8 27 USD Issue a refund EJ You have up to 60 days to refund the payment and get the fees back Item Amount 8 88 USD Shipping 0 00 USD Handling 0 00 USD Quantity 1 Date Feb 25 2010 Time 16 19 21 PST Status Completed Direct Payment and Virtual Terminal transactions are not covered by PayPal s seller protection policies and programs Lear
110. uthorization request to identify the authorization that you want to reauthorize lt form method post action https sandbox paypal com nvp gt lt input type hidden name USER value gt lt input type hidden name PWD value gt lt input type hidden name SIGNATURE value gt lt input type hidden name VERSION value 62 0 gt lt input type hidden name AUTHORIZATIONID value 4HS1916972552122T gt lt input type hidden name AMT value 23 gt lt input type hidden name CURRENCYCODE value USD gt lt input type submit name METHOD value DoReauthorization gt lt form gt The response to DoReauthorization contains a new authorization ID 42 April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment Direct Payment Authorization and Captures AUTHORIZATIONID 6HB59926VL998415S amp TIMESTAMP 2010 2d03 2d08T20 3a37 3a48Z amp CO RRELATIONID 797da6e380c0 amp ACK Success amp VERS ION 62 2e0 amp BUILD 1218643 amp PAYMENTST ATUS Pending amp PENDINGREASON authorizat ion amp PROTECTIONELIGIBILITY Ineligible Use the new authorization ID in the DoCapture request lt form method post action https sandbox paypal com nvp gt lt input type hidden name USER value gt lt input type hidden name PWD value gt lt input type hidden name SIGN
111. ver you can change the amount before calling the DoExpressCheckoutPayment API if you did not know the total amount when you called the SetExpressCheckout API This example assumes the simplest case in which the total amount was specified in the return URL when calling the Set ExpressCheckout API Although you can specify additional options this example does not use any additional options To execute an Express Checkout transaction 1 Specify that you want to execute the DoExpressCheckoutPayment API operation and the version you want to M VERSION XX 0 48 use ETHOD DoExpressCheckoutPayment April 2012 PayPal Payments Pro Integration Guide Getting Started With Express Checkout EN Testing an Express Checkout Integration 2 Specify your API credentials Use the following parameters for a signature USER API_usemame PWD API_password SIGNATURE API_signature 3 Specify the token returned by PayPal when it redirects the buyer s browser to your site PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API TOKEN tokenValue 4 Specify the Payer ID returned by PayPal when it redirects the buyer s browser to your site PayPal returns the Payer ID to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API Optionally you can o
112. w information on the checkout page that shows where to find the CSC code on the card and provide a brief explanation of its purpose e Configure timeout settings to allow for the fact that the DoDirectPayment API operation might take as long as 60 seconds to complete even though completion in less than 3 seconds is typical Consider displaying a processing transaction message to the buyer and disabling the Pay button until the transaction finishes e Use the optional Invoice ID field to prevent duplicate charges PayPal ensures that an Invoice ID is used only once per account Duplicate requests with the same Invoice ID result in an error and a failed transaction PayPal Payments Pro Integration Guide April 2012 21 I Introducing Direct Payment User Interface Recommendations for Direct Payment Checkout 22 April 2012 PayPal Payments Pro Integration Guide Introducing Express Checkout Express Checkout is PayPal s premier checkout solution that streamlines the checkout process for buyers and keeps them on a merchant s website after making a purchase e The Express Checkout Experience e Express Checkout Integration Steps e Express Checkout Flow e Express Checkout Building Blocks The Express Checkout Experience Express Checkout makes it easier for buyers to pay online It also enables you to accept PayPal while retaining control of the buyer and the overall checkout flow Consider your buyers experience before implement
113. w it was executed The following diagram shows fields in the response to a PayPal NVP API operation Your Site i NVP Response A 1 i ACK Success cede TIMESTAMP 2008 2d04 2 PayPal Ack To Cast de CORRELATIONID 63cdacOb da VERSION 52 2e000000 API Server BUILD 1 2e0006 Response specific fields The sados amador anp do pay Xem Common Response Fields The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation A PayPal API response includes the following fields Field Description ACK Acknowledgement status which is one of the following values e Success indicates a successful operation e SuccessWithWarning indicates a successful operation however there are messages returned in the response that you should examine e Failure indicates the operation failed the response also contains one or more error messages explaining the failure e FailureWithWarning indicates that the operation failed and that there are messages returned in the response that you should examine CORRELATIONID Correlation ID which uniquely identifies the transaction to PayPal TIMESTAMP The date and time that the requested API operation was performed VERSION The version of the API BUILD The sub version of the API Error Responses If the ACK value is not Success API response fields may not be returned An error response has the following general form
114. yments from PayPal accounts in addition to debit and credit cards The following diagram shows the relationship between Direct Payment and Express Checkout to a buyer PayPal Payments Pro Integration Guide April 2012 j Introducing PayPal Payments Pro Additional Features of PayPal Payments Pro Customer enters Tait TRENT MIHIR gt x L information on Billing Customer pays 2 ona your website with a credit or a debit card pr E v gan Shopping Cart Confirmation PayPal processes payment d Customer confirms PayPal purchase and Stored Shipping returns to your site fan easy seve amp Billing Info Customer pays with PayPal From your shopping cart a buyer can either checkout with Express Checkout starting from the Checkout with PayPal button on your Shopping Cart page or pay directly by credit or debit card using Direct Payment If a buyer pays using Express Checkout PayPal provides a checkout experience that streamlines checkout Even if buyers do not pay using Express Checkout they can still pay by credit or debit card using Direct Payment In this case buyers might need to enter payment billing and shipping information In both cases buyers stay on your website or are sent to the page of your choice You must implement both an Express Checkout flow and a Direct Payment flow to use PayPal Payments Pro You implement the Express Checkout flow by calling PayPal s Expres
115. ys of the authorization Express Checkout provides an additional option called an order which you use when a single authorization is insufficient You can create multiple authorizations and capture them as part of the same order This would be useful for example when an order is split into multiple shipments and you need to capture a payment each time part of the order is shipped Recurring Payments You can support recurring payments to manage subscriptions and other payments on a fixed schedule Direct Payment and Express Checkout both process recurring payments When you support recurring payments for a buyer you create a recurring payments profile The profile contains information about the recurring payments including details for an optional trial period and a regular payment period Both periods contain information about the payment frequency and payment amounts including shipping and tax if applicable After creating a profile PayPal automatically queues payments based on the billing start date billing frequency and billing amount Payments reoccur until the profile expires there are too many failed payments to continue or you cancel the profile Permission to allow recurring payments is established by the buyer setting up a billing agreement with the merchant on PayPal For Express Checkout the billing agreement can be established either in advance or when the buyer first makes a purchase in either case it occurs when you c
116. zation and Capture for Direct Payment An authorization payment action represents an agreement to pay and places the buyer s funds on hold for up to three days To set up an authorization specify the following payment action in your DoDirectPayment request PAYMENTACTION Authorization An authorization enables you to capture multiple payments up to 115 of or USD 75 more than the amount you initially specify in the DoDirectPayment request Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately The honor period for which funds can be held is 3 days The valid period for which the authorization is valid is 29 days You can reauthorize the 3 day honor period at most once within the 29 day valid period April 2012 PayPal Payments Pro Integration Guide Getting Started With Direct Payment Direct Payment Authorization and Captures Captures attempted outside of the honor period result in PayPal contacting the card issuer to reauthorize the payment however the reauthorization and thus the capture might be declined If you know that you will capture after the honor period expires PayPal recommends that you call DOReauthorization to explicitly reauthorize the honor period before attempting to capture the payment Consider an example in which the buyer orders three 100 items for a total of 300 You specify Authorization for your pay

Download Pdf Manuals

Related Search

Related Contents

RCA RP5130 User's Manual  90 - Mep S.p.A.  MI-CHAUD, MI-FROID-DP-V3 - L`ARTCHIPEL Scène nationale de la  pdf 289KB  Samsung SPF-105V Benutzerhandbuch  SMARTwobble User Manual  AIR GUARD KONK 400  Tableau prog  2705-ND003, Keypad Software User Manual  Manual de instalación - Homocrisis by Toshiba Calefacción & Aire  

Copyright © All rights reserved. Failed to retrieve file