PayPal Pro - 2012 User's Guide

PayPal Pro Integration GuideLast updated: July 2012

Getting Started with PayPal ProHow PayPal Pro Works10 Supports Major Credit and Debit Cards - Supports Visa, MasterCard, Carta Aura (processed by Cet

Getting Started with PayPal ProSeller ProtectionSeller ProtectionIf PayPal is the only payment method on your website, transactions processed through

Getting Started with PayPal ProPayPal Express Checkout Transaction Processing12 Verifying the status of a transaction programatically. To check the i

Getting Started with PayPal ProIntroduction to Integrating with PayPal Proplaced on both the product page as well as the shopping cart page and is a g

Getting Started with PayPal ProIntroduction to Integrating with PayPal Pro14

2Integrating Your Website Using HTMLThis chapter provides instructions for a simple integration that enables you to begin processing transactions usin

Integrating Your Website Using HTMLSimple PayPal Pro Integration16The return URL is appended with a Transaction ID on the query string during the redi

17Integrating Your Website Using HTMLHTML VariablesHTML VariablesThe table below lists the PayPal Pro HTML variables you can use to send in additional

Integrating Your Website Using HTMLHTML Variables18cancel_returnThe browser will be redirected to this URL if the buyer clicks “Return to Merchant” li

19Integrating Your Website Using HTMLHTML VariablesreturnThe URL to which the buyer’s browser is redirected to after completing the payment. Be sure t

PayPal Pro Integration GuideDocument Number: 10116.en_US-201207© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, In

Integrating Your Website Using HTMLHTML Variables20

213Customising Your PayPal Payment PageYou can customise the look and feel of the PayPal payment page in the following two ways: Modifying Your PayPa

Customising Your PayPal Payment PageModifying Your PayPal Account Settings22

Customising Your PayPal Payment PageModifying Your PayPal Account SettingsSettingsThis page allows you to select the information you want to collect a

Customising Your PayPal Payment PageModifying Your PayPal Account Settings24What information do you want to show on your PayPal Pro payment page?You c

Customising Your PayPal Payment PageModifying Your PayPal Account SettingsCustomisation

Customising Your PayPal Payment PageModifying Your PayPal Account Settings26This page allows you to customise your payment page. You can customise the

Customising Your PayPal Payment PageModifying Your PayPal Account SettingsChoosing a TemplateChoose from the following three design templates: Templa

Customising Your PayPal Payment PageModifying Your PayPal Account Settings28Template B. Customise the header, background, title, button, and the order

Customising Your PayPal Payment PageModifying Your PayPal Account SettingsTemplate C. Customise the header, background, title, and the button.FIGURE 3

ContentsPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7About This Guide. . . . .

Customising Your PayPal Payment PageModifying Your PayPal Account Settings30Customising Your TemplateConsider the following when you customise your te

Customising Your PayPal Payment PageAdding HTML VariablesAdding HTML VariablesThe table below lists the PayPal Pro HTML variables you can use to custo

Customising Your PayPal Payment PageAdding HTML Variables32showCustomerNameDisplay customer name (first name and last name). Default Value: true All

4Integrating iFrame in Your WebsitePayPal offers a compact payment form that can be integrated in an iFrame on your website. Since this form is integr

Integrating iFrame in Your WebsiteIntegrating iFrame34Integrating iFrameChoose one of the following methods to integrate the compact payment form in y

35Integrating iFrame in Your WebsiteIntegrating iFrame3. Ensure that the target name matches the iFrame name, as highlighted in the example below:<

Integrating iFrame in Your WebsiteIntegrating iFrame36Using URL Returned in the ResponseIn the URL identified in the response as EMAILLINK, add “src”

37Integrating iFrame in Your WebsiteIntegrating iFrameExample of API (Form POST) IntegrationThe complete example as per the above steps is as follows:

Integrating iFrame in Your WebsiteIntegrating iFrame38

5Integrating Your Website Using APIUsing the Button Manager API, you can programmatically create the checkout button that initiates the PayPal Pro che

Contents4Chapter 5 Integrating Your Website Using API . . . . . . . . . . . . .39Button Hosting . . . . . . . . . . . . . .

Integrating Your Website Using APIUsing the Button Manager API with PayPal Pro Checkout40Using the Button Manager API with PayPal Pro CheckoutTo creat

41Integrating Your Website Using APIUsing the Button Manager API with PayPal Pro CheckoutExample of ENCRYPTEDEMAILLINK=https://www.paypal.com/acquirin

Integrating Your Website Using APIUsing the Button Manager API with PayPal Pro Checkout42Example for TOKENWEBSITECODE=<form action="https://ww

43Integrating Your Website Using APIUsing the Button Manager API with PayPal Pro CheckoutN OTE: The PayPal payment page displays a button identified a

Integrating Your Website Using APIUsing the Button Manager API with PayPal Pro Checkout44L_BUTTONVAR23=notify_url=www.yourcompany.comL_BUTTONVAR24=cus

45Integrating Your Website Using APIBMCreateButton API OperationBMCreateButton API OperationUse the BMCreateButton API operation to create PayPal Pro

Integrating Your Website Using APIBMCreateButton API Operation46BMCreateButton ResponseThe response contains an ID if the button is hosted on PayPal,

47Integrating Your Website Using APIBMCreateButton API Operation11934 Invalid Data You must specify the same number of entries for option prices and s

Integrating Your Website Using APIBMCreateButton API Operation48

496Testing Your Integration in SandboxThe PayPal Sandbox is a self-contained environment within which you can prototype and test PayPal features. The

5ContentsGetTransactionDetails API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63GetTransact

Testing Your Integration in SandboxCreating a Preconfigured Account50To test your PayPal Pro integration, create a preconfigured account using the fol

Testing Your Integration in SandboxCreating a Preconfigured Account3. Choose Italy from the Country drop-down menu.4. Select Website Payments Pro as t

Testing Your Integration in SandboxCreating a Preconfigured Account528. Click Enter Sandbox Test Site. The Sandbox Test Site appears in a different br

Testing Your Integration in SandboxTesting Your Integration and SettingsTesting Your Integration and SettingsThe following sections contain informatio

Testing Your Integration in SandboxTesting Your Integration and Settings54Testing Your SettingsTo change the look and feel of your payment page, modif

557Order ProcessingThis chapter walks you through the end of end order processing experience. It includes information about verifying the status and a

Order ProcessingFulfilling Order56Execute a GetTransactionDetails API CallUsing GetTransactionDetails API, you can obtain information about a specific

8Protecting Buttons by Using Encrypted Website PaymentsUsing Encrypted Website Payments helps secure payment buttons that you generate or write manual

Protecting Buttons by Using Encrypted Website PaymentsPublic Key Encryption Used by Encrypted Website Payments58Public Key Encryption Used by Encrypte

59Protecting Buttons by Using Encrypted Website PaymentsSetting Up Certificates Before Using Encrypted Website PaymentsGenerating Your Private Key Usi

Contents6

Protecting Buttons by Using Encrypted Website PaymentsSetting Up Certificates Before Using Encrypted Website Payments60Downloading the PayPal Public C

61Protecting Buttons by Using Encrypted Website PaymentsSetting Up Certificates Before Using Encrypted Website PaymentsUsing Encrypted Website Payment

Protecting Buttons by Using Encrypted Website PaymentsSetting Up Certificates Before Using Encrypted Website Payments62where the argument is:– CertFil

A 63Optional API OperationsUsing the Transaction ID, a number of PayPal API operations are available. The most commonly used for PayPal Pro are: Get

Optional API OperationsGetTransactionDetails API64GetTransactionDetails ResponseN OTE: All fields defined in the formal structure of GetTransactionDet

Optional API OperationsGetTransactionDetails APIPayer Information FieldsPayer Name FieldsTABLE A.3 Payer Information FieldsField DescriptionEMAILEmail

Optional API OperationsGetTransactionDetails API66Address FieldsSUFFIXPayer’s suffix.Character length and limitations - 12single-byte alphanumeric cha

Optional API OperationsGetTransactionDetails APIPayment Information FieldsTABLE A.6 Payment Information FieldsField DescriptionTRANSACTIONIDUnique tra

Optional API OperationsGetTransactionDetails API68FEEAMTPayPal fee amount charged for the transactionCharacter length and limitations - Does not excee

Optional API OperationsGetTransactionDetails APIPAYMENTSTATUSStatus of the payment.The status of the payment: None - No status Canceled-Reversal - A

PPrefaceAbout This GuideThe PayPal Pro Integration Guide describes how to integrate with PayPal Pro. It includes information about: Features and bene

Optional API OperationsGetTransactionDetails API70PENDINGREASONNOTE: PendingReason is returned in the response only if PaymentStatus is Pending.The re

Optional API OperationsGetTransactionDetails APIPayment Item Information FieldsPROTECTIONELIGIBILITYSince version 64.4, the kind of seller protection

Optional API OperationsGetTransactionDetails API72Payment Item FieldsAuction FieldsTABLE A.8 Payment Item FieldsField DescriptionL_DESCnAmount of tax

Optional API OperationsRefundTransaction APISubscription Term FieldsRefundTransaction APIIssue a refund to the PayPal account holder associated with a

Optional API OperationsDoCapture API74RefundTransaction Response DoCapture APICapture an authorized payment. DoCapture Request DoCapture ResponseDoC

Optional API OperationsDoCapture APICOMPLETETYPE(Required) The value Complete indicates that this the last capture you intend to make.The value NotCom

Optional API OperationsDoCapture API76SOFTDESCRIPTOR(Optional) The soft descriptor is a per transaction description of the payment that is passed to t

Optional API OperationsDoCapture APIDoCapture Response  DoCapture Response Fields PayerInfo Type Fields Ship To Address Fields Payer Name FieldsN

Optional API OperationsDoCapture API78Ship To Address FieldsBUSINESSPayer’s business name.Character length and limitations - 127 single-byte character

Optional API OperationsDoCapture APIPayer Name FieldsTABLE A.17 Payer Name FieldsField DescriptionSALUTATIONPayer’s salutation.Character length and li

PrefaceDocumentation FeedbackP8Documentation FeedbackHelp us improve this guide by sending feedback to:[email protected]

Optional API OperationsDoCapture API80

B 81Moving from Website Payments Standard to PayPal ProIf you are moving from Website Payment Standard to PayPal Pro, you must make the following cha

Moving from Website Payments Standard to PayPal Pro82Sample Code ComparisonBelow is a comparison of Website Payment Standard code and PayPal Pro code.

Moving from Website Payments Standard to PayPal Pro<input type="hidden" name="city" value="San Jose"><input typ

Moving from Website Payments Standard to PayPal Pro84

C 85Error MessagesThe table below lists error codes and the appropriate correction action.TABLE C.1 Error Codes and the Corresponding Corrective Acti

Error Messages8610507 Your payment can't be processed. Please contact the merchant directly with this code.Your PayPal account is restricted. Con

87Error Messages10539 Your payment can't be processed. Please contact the merchant directly with this code.Transaction was declined by fraud filt

Error Messages8810552 Your payment can't be processed. Please contact the merchant directly with this code.Merchant account attempting the transa

89Error Messages10702 Please enter a valid address in line 1 of the billing address.Buyer should enter a valid address in line 1 of the bill-ing addre

91Getting Started with PayPal ProOverviewPayPal Pro is a payment platform allowing merchants to receive payments funded by card or PayPal account.This

Error Messages9010719 Please enter a valid addressee name in the shipping address.Buyer should enter a valid addressee name for shipping address.10720

91Error Messages10735 Please enter a valid postal code in the shipping address.Buyer should enter a valid postal code in the shipping address.10736 Pl

Error Messages9210761 Your payment can't be processed because this transaction appears to be a duplicate of a recent transaction.Transaction was

93Error Messages15008 Your payment can't be processed. Please contact the merchant directly with this code.Review your integration to ensure that

Error Messages94

D Currency CodesThe table below lists all the currencies supported by PayPal. TABLE D.1 Currency CodesCurrency Code Country NameAUD Australian Dollar

Currency Codes96

97IndexAaddress_override 17address1 17address2 17API integration 39Bbackground 30billing_address1 17billing_address2 17billing_city 17billing_country

Index98Hhandling 18header 30headerBgColor 31headerHeight 31HOSTED 39HOSTEDBUTTONID 46HTML integration 15HTTP variables 17, 31IiFrames 33API integratio

99IndexshowCustomerName 32showHostedThankyouPage 32showShippingAddress 32simple integration 15state 19subheaderText 32subtotal 19Ttax 19template 32Tem