PayPal Pro Integrace Guide
Below you will find brief information for PayPal Pro Integration. This guide helps merchants integrate PayPal Pro into their websites, enabling them to accept payments via credit cards and PayPal accounts. It covers features like Seller Protection, Instant Payment Review, and customization options for the hosted payment page. The guide also details integration methods using HTML and APIs, along with sandbox testing and transaction verification.
Advertisement
Advertisement
PayPal Pro
Integration Guide
Last updated: July 2012
PayPal Pro Integration Guide
Document Number: 10116.en_US-201207
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., 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 herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1 Getting Started with PayPal Pro . . . . . . . . . . . . . . . 9
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
How PayPal Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Seller Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Instant Payment Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
PayPal Express Checkout Transaction Processing . . . . . . . . . . . . . . . . . . . . . 12
Introduction to Integrating with PayPal Pro . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2 Integrating Your Website Using HTML. . . . . . . . . . . . 15
Simple PayPal Pro Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Sample Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 3 Customising Your PayPal Payment Page . . . . . . . . . . 21
Modifying Your PayPal Account Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Customisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Adding HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 4 Integrating iFrame in Your Website . . . . . . . . . . . . . 33
Integrating iFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Manual Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
API Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4
Contents
Chapter 5 Integrating Your Website Using API . . . . . . . . . . . . . 39
Button Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Using the Button Manager API with PayPal Pro Checkout . . . . . . . . . . . . . . . . . 40
Using URL Returned in the Response (Recommended) . . . . . . . . . . . . . . . . 40
Using Form POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Encrypting Buttons Using Public and Private Key . . . . . . . . . . . . . . . . . . . . 43
Example of Initiating PayPal ProCheckout . . . . . . . . . . . . . . . . . . . . . . . 43
BMCreateButton API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
BMCreateButton Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
BMCreateButton Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
BMCreateButton Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Chapter 6 Testing Your Integration in Sandbox . . . . . . . . . . . . 49
Creating a Preconfigured Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Testing Your Integration and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Testing Your Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Testing Your Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 7 Order Processing . . . . . . . . . . . . . . . . . . . . . . 55
Verifying Transaction Status and Authenticity . . . . . . . . . . . . . . . . . . . . . . . . 55
Validate Instant Payment Notification (IPN) . . . . . . . . . . . . . . . . . . . . . . . 55
Execute a GetTransactionDetails API Call. . . . . . . . . . . . . . . . . . . . . . . . 56
Fulfilling Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Chapter 8 Protecting Buttons by Using Encrypted Website Payments 57
Public Key Encryption Used by Encrypted Website Payments . . . . . . . . . . . . . . . 58
Setting Up Certificates Before Using Encrypted Website Payments. . . . . . . . . . . . . 58
Generating Your Private Key Using OpenSSL. . . . . . . . . . . . . . . . . . . . . . 59
Generating Your Public Certificate Using OpenSSL . . . . . . . . . . . . . . . . . . . 59
Uploading Your Public Certificate to Your PayPal Account . . . . . . . . . . . . . . . 59
Downloading the PayPal Public Certificate from the PayPal Website . . . . . . . . . . 60
Removing Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Using Encrypted Website Payments to Protect Your Payment Buttons . . . . . . . . . 61
Blocking Unprotected and Non-encrypted Website Payments . . . . . . . . . . . . . 62
Appendix A Optional API Operations . . . . . . . . . . . . . . . . . . . 63
Contents
GetTransactionDetails API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
GetTransactionDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
GetTransactionDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
RefundTransaction API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
DoCapture API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
DoCapture Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Chapter B Moving from Website Payments Standard to PayPal Pro . . 81
Sample Code Comparison. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Appendix C Error Messages . . . . . . . . . . . . . . . . . . . . . . . 85
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . . 95
5
6
Contents
P
Preface
About This Guide
The PayPal Pro Integration Guide describes how to integrate with PayPal Pro. It includes information about:
Features and benefits of PayPal Pro.
Seller Protection.
Moving from Website Payments Standard to PayPal Pro.
Integrating your website with PayPal Pro.
Customising your hosted payment page.
Testing your integration in the Sandbox environment.
Verifying the status and authenticity of the transactions before fulfilling the orders.
Intended Audience
This guide is for merchants and developers that want to integrate with PayPal Pro to add transaction processing to their website.
Revision History
Revision history for Website Payments Pro Hosted Solution Integration Guide.
Date
July 2012
June 2012
May 2012
T ABLE P.1 Revision History
Description
Removed references to the deprecated HTML variable: shopping_url
Updated the requirements for the billing address fields in the
Added a character limitations note to the following sections:
BMCreateButton API Operation .
Corrected the HTML samples in Chapter 2 and
Added IE9 to list of browsers that support iFrame.
8
P
Preface
Documentation Feedback
Documentation Feedback
Help us improve this guide by sending feedback to: [email protected]
1
Getting Started with PayPal Pro
Overview
PayPal Pro is a payment platform allowing merchants to receive payments funded by card or
PayPal account.This solution is hosted by PayPal. You do not have to capture or store credit card information on your website, thereby helping towards achieving PCI compliance.
PayPal Pro is the choice for merchants who prefer a solution where all financial details are handled by PayPal.
In addition to PayPal Pro, PayPal recommends that you implement the PayPal Express
Checkout button on your website. The button appears much earlier in the payment flow and gives existing PayPal account holders the opportunity to use PayPal, thereby increasing the transaction completion rate.
Features and Benefits
Here are the features and benefits of PayPal Pro:
PCI compliance - Payment Card Industry (PCI) Data Security Standards (DSS) is a global security standard which applies to all businesses that collect, store, process, or transmit card holder information. You can use PayPal’s hosted payment page as part of the PCI compliance solution for your business.
N
OTE
: PayPal Pro implementation helps achieving PCI compliance, and does not necessarily guarantee it.
Supports iFrame - PayPal offers a compact payment form that can be integrated in an iFrame on your website. The buyer completes the payment on your website and you can maintain the checkout look and feel in the master frame that surrounds the compact form.The credit card fields are part of the compact form so you do not have to collect this
information separately. For more information, refer to Chapter 4, “Integrating iFrame in
.
Soluzione di Pagamento Telefonico - PayPal-hosted online payment form, which enables you to accept phone fax, mail orders for all major credit cards.
Seller Protection - This program protects you against chargebacks on transactions funded by credit card or a PayPal account. For more information, refer to
“Seller Protection” on page 11
PayPal Express Checkout - Two-click payment option for PayPal account holders. For
more information, refer to “PayPal Express Checkout Transaction Processing” on page 12 .
9
Getting Started with PayPal Pro
How PayPal Pro Works
Supports Major Credit and Debit Cards - Supports Visa, MasterCard, Carta Aura
(processed by Cetelem), Postepay (Visa), PayPal prepaid card (MasterCard).
How PayPal Pro Works
10
In the figure above, the top flow is for paying using your PayPal account and the bottom flow is for paying with a card.
To integrate your website with PayPal Pro:
1. Generate a button in your website checkout flow using HTML or API solution. The button could be labeled Pay or Buy or similar. When the buyer clicks this button, they are redirected to the payment page hosted by PayPal.
2. On the payment page, the buyer enters their debit or credit card information and clicks the
Pay Now button.They do not have to have a PayPal account, although they have the option to use it if they have one.
3. If the transaction is successful, the buyer either sees PayPal’s confirmation page or is redirected to a URL you specify. If the transaction is unsuccessful, an error message is displayed, and the buyer can rectify the error and retry the transaction.
You can specify the content of the payment page and configure its appearance to reflect the look and feel of your website (including your logo).
Getting Started with PayPal Pro
Seller Protection
Seller Protection
If PayPal is the only payment method on your website, transactions processed through Intégral
Evolution are eligible for PayPal’s Seller Protection. It covers payments done through the payment flow of your website for items sold domestically and internationally. These items can be purchased using a credit card or through the PayPal account.
To benefit from Seller Protection, the purchased item must be shipped to the address you communicated to PayPal.
For this, you must perform the following tasks:
Send all the details of the billing and shipping address provided by the buyer in the Form
POST.
Set the address_override
variable to true
and showShippingAddress
variable to false
(or unselect it in the Settings page on your Profile page).
IMPORTANT: Conditions apply. To see all conditions, please refer to PayPal e-Terminal and
PayPal Intégral Evolution User Agreement.
Instant Payment Review
To take advantage of Seller Protection, you must integrate with Instant Payment Review.
Payment Review is a feature that identifies high-risk transactions and notifies you so that you can hold shipments until the risk has been evaluated by PayPal. It is made available to all merchants and it reduces seller loss and makes the transactions eligible for Seller Protection.
When a transaction is initiated, PayPal runs additional buyer-risk assessment. PayPal scores all transactions (Authorization and Sale) instantly and flags high-risk transactions as “Under
Review” and you are immediately notified. You should not ship merchandise or, in the case of electronic media, you should not allow download access while the payment is under review.
PayPal fraud agents review the transaction within 24 hours and update the order as Completed
(released as safe by Payment Review) or Reversed (rejected by Payment Review). For risky transactions, PayPal advises you to not ship the items until the transaction has been determined as Completed. Payments that are completed are eligible for PayPal’s Seller Protection.
You can determine the status of a payment in the following ways:
Logging into https://www.paypal.com and viewing the status information in the
Transaction History.
Checking email sent by PayPal
Reviewing the Instant Payment Notification (IPN) message
12
Getting Started with PayPal Pro
PayPal Express Checkout Transaction Processing
Verifying the status of a transaction programatically. To check the initial status of a transaction, use any of the following API operations:
– DoExpressCheckoutPayment
– DoReferenceTransaction
– DoAuthorization
– DoReauthorization
You can check the subsequent status of a transaction programatically by calling the
GetTransactionDetails API operation. For more information, refer to
N
OTE
: You must use version 58.0 (or +) of the API to obtain the initial status information provided by DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, or DoReauthorization.
To use payment review with DoExpressCheckoutPayment, DoReferenceTransaction,
DoAuthorization, and DoReauthorization Payment API operations, you must
1. Check the payment status in the response to the API operation; specifically, check whether
PaymentStatus
is set to Pending.
2. If the
PaymentStatus
is set to
Pending
, check whether the
PendingReason
is set to
PaymentReview
, because there are other reasons that a transaction may become pending.
For example, an unsettled authorization’s
PaymentStatus
is set to
Pending
; however, its
PendingReason
is set to authorization, which is not related to payment review.
If
PaymentStatus
is set to
Pending
and the
PendingReason
is set to
PaymentReview
, you should not ship merchandise or, in the case of electronic media, you should not allow download access.
Because the payment status will change after review, you must periodically check the payment status using the GetTransactionDetails API operation, checking email from PayPal, reviewing
IPN messages, or checking the Transaction History on https://www.paypal.com
.
PayPal Express Checkout Transaction Processing
PayPal Express Checkout is PayPal’s premier checkout solution. It makes it easier for your buyers to pay and allows you to accept PayPal while retaining control of the buyer and overall checkout flow. It enables the buyers to use shipping information stored securely at PayPal to check out, so they do not have to re-enter it on your site. The Pay with PayPal button can be
Getting Started with PayPal Pro
Introduction to Integrating with PayPal Pro placed on both the product page as well as the shopping cart page and is a great tool to increase checkout conversion.
The following steps describe how PayPal Express Checkout works
1. After selecting products to purchase on your website, buyers click Pay with PayPal button.
2. They are redirected to the PayPal site where they log in using their PayPal login and password.
3. After logging in, they review the order summary, and click Continue Checkout to authorise the transaction.
4. The buyers are then returned to the confirmation page on your website where they can verify the order details and submit the transaction.
For complete details on PayPal Express Checkout, refer to Express Checkout Integration Guide .
Introduction to Integrating with PayPal Pro
After signing up for PayPal Pro, follow these steps to integrate your website with:
1. Connect your website to PayPal Pro: Identify a point in your website checkout flow where you want to place a Pay or similar button that the buyer clicks on to initiate the payment.
You can do this using HTML or API. Clicking on this button redirects the buyer’s browser to PayPal’s payment page for transaction processing. Depending on how you want to
integrate, follow the steps described in Chapter 2, “Integrating Your Website Using HTML
or
Chapter 5, “Integrating Your Website Using API .
2. Optionally, customise the appearance and content of your PayPal-hosted payment page by either sending the appropriate HTTP variables or by editing your PayPal account settings.
Refer to
Chapter 3, “Customising Your PayPal Payment Page
.
3. Optionally, test your integration in the PayPal Sandbox environment. This step is described
in Chapter 6, “Testing Your Integration in Sandbox
.
14
Getting Started with PayPal Pro
Introduction to Integrating with PayPal Pro
2
Integrating Your Website Using
HTML
This chapter provides instructions for a simple integration that enables you to begin processing transactions using PayPal Pro.
N
OTE
: PayPal recommends that you implement the simple integration to familiarise yourself with PayPal Pro before implementing a more customised integration.
As part of a simple integration, you get the default settings on your payment page. To customise the look and feel of the page so it matches your website, you can do one of the following:
Change your settings in your Profile section on PayPal.com, as described in
Your PayPal Account Settings” on page 21
.
Add the appropriate HTML variables to the payment page, as described in Table 2.1,
“HTML Variables for Settings of Payment Page
and
Table 3.1, “HTML Variables for Look and Feel of Payment Page
.
IMPORTANT: HTML variables will override the settings you save on your profile page.
Simple PayPal Pro Integration
To integrate your website with PayPal Pro, identify a point in your website checkout flow where you want to place a button that the buyer clicks to initiate the payment. The button should be labeled Continue to Payment, Pay or similar, and when clicked, should execute a
Form POST to PayPal. Clicking on this button redirects the buyer’s browser to the PayPal payment page where they can pay with credit card, or their PayPal account.
The Form POST contains a set of HTML variables that describe the transaction. In the Form
POST, you must specify the following:
subtotal
- amount of the transaction
business
- Secure Merchant ID (found on the profile page) or the email address associated with your PayPal account.
paymentaction
- Indicates whether the transaction is for payment on a final sale or an authorisation for a final sale (to be captured later).
The default currency is USD. Additionally, you can specify the appropriate HTML variables
listed in Table 2.1, “HTML Variables for Settings of Payment Page
to customise the
to customise the look and feel of the page. If the payment is successful, then the buyer either sees the PayPal confirmation page or is redirected to the URL you specify in your configuration.
16
Integrating Your Website Using HTML
Simple PayPal Pro Integration
The return URL is appended with a Transaction ID on the query string during the redirect back from the payment page to your website. This Transaction ID can be used to retrieve the status and verify the authenticity of the transaction. For detailed information on verifying the authenticity of the transaction before fulfilling the order, refer to
Sample Integration
Below is an example of a simple PayPal Pro integration:
1. Sample PayPal Pro Form POST:
<form action="https://securepayments.paypal.com/cgi-bin/acquiringweb" method="post">
<input type="hidden" name="cmd" value="_hosted-payment">
<input type="hidden" name="subtotal" value="50">
<input type="hidden" name="business" value="HNZ3QZMCPBAAA">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="return" value="https://yourwebsite.com/receipt_page.html">
<input type="submit" name="METHOD" value="Pay">
</form>
The bold text is the value for the corresponding variable. It is recommended that you enclose the values in quotes. For detailed information on these values, refer to
“HTML Variables for Settings of Payment Page
.
2. Output the HTML text into your website at the point where buyers will proceed with their checkout.
3. Open your checkout page and test the button to ensure that it opens the PayPal payment page.
You can also use the PayPal sandbox environment to test your integration. For complete information on testing your integration in the PayPal Sandbox environment, refer to
Chapter 6, “Testing Your Integration in Sandbox
.
Integrating Your Website Using HTML
HTML Variables
HTML Variables
The table below lists the PayPal Pro HTML variables you can use to send in additional transaction information along with your web request. For a list of HTML variables that you can use to customise the look and feel of your payment page, refer to
Variables for Look and Feel of Payment Page
.
N
OTE
: The values you pass must not contain any of these special characters (){}<>\";
N
OTE
: Some merchants are required to pass billing information with every transaction. It is recommended that you test your integration first, particularly if you plan to use iFrame, to determine if the billing information fields are required.
Variable address1 address2
T ABLE 2.1 HTML Variables for Settings of Payment Page address_override billing_address1 billing_address2 billing_city billing_country billing_first_name billing_last_name billing_state billing_zip
Description
Street name of shipping address. (1 of 2 fields).
Street name of shipping address. (2 of 2 fields).
The payer is shown the passed-in address but cannot edit it. This variable is overridden if there are errors in the address. The allowable values are true/false. Default is false.
Street name of the billing address. (1 of 2 fields).
Street name of the billing address. (2 of 2 fields).
City name of the billing address.
Country code of the billing address.
First name of person the item is being billed to.
Last name of person the item is being billed to.
State name of the billing address.
Zip code of the billing address.
Required
No
No
No
No
bn business buyer_email
Identifies the source that built the code for the button.
Format - <Company>_<Service>_<Product>_<Country>
Your PayPal account email address or your PayPal ID
(Secure Merchant ID) associated with your PayPal account. It is recommended that you use your PayPal ID, which can be found on the top section of the Profile page on PayPal.com
Email address of the buyer.
No
Yes
No
17
18
Integrating Your Website Using HTML
HTML Variables
Variable cancel_return cbt city country currency_code custom first_name handling invoice last_name lc night_phone_a night_phone_b night_phone_c notify_url
T ABLE 2.1 HTML Variables for Settings of Payment Page (Continued) paymentaction
Description
The browser will be redirected to this URL if the buyer clicks “Return to Merchant” link. Be sure to enter the complete URL, including http:// or https://.
Sets the text for the “Return to Merchant” link on the
PayPal confirmation page. For business accounts, the return button displays your business name in the place of the word “Merchant” by default.
City name of shipping address.
Country name of shipping address.
The currency of the payment. The default is USD.
Pass through variable never presented to the payer.
First name of person the item is being shipped to.
Handling charged. This amount is added to subtotal
for the total amount.
Required
No
No
No
No
No
No
No
No
Order number in the merchant’s ordering/invoice system. No
Last name of person the item is being shipped to.
No
The language of the login or sign-up page.
The area code of the U.S. phone number, or the country code of the phone number outside the U.S. This prepopulates the buyer’s home phone number.
No
No
No The three-digit prefix for U.S. phone numbers, or the entire non-U.S. phone number for numbers outside the
U.S., excluding the country code. This pre-populates the buyer’s home phone number.
N
OTE
: Use this variable for non-US numbers.
The four-digit phone number for U.S. phone numbers.
This pre-populates the buyer’s home phone number.
The URL to which PayPal posts information about the transaction in the form of Instant Payment Notification. Be sure to enter the complete URL, including http:// or https://.
Indicates whether the transaction is for payment on a final sale or an authorisation for a final sale (to be captured later).
Allowable Values: - authorization or sale
Default Value - sale
No
No
Yes
Integrating Your Website Using HTML
HTML Variables
Variable return shipping state subtotal tax zip
T ABLE 2.1 HTML Variables for Settings of Payment Page (Continued)
Description
The URL to which the buyer’s browser is redirected to after completing the payment. Be sure to enter the complete URL, including http:// or https://.
Shipping charged. This amount is added to subtotal
for the total amount.
State of the shipping address.
Amount charged for the transaction. If shipping, handling, and taxes are not specified, this is the total amount charged.
Taxes charged. This amount is added to subtotal
for the total amount.
Postal code of the shipping address.
Required
No
No
No
Yes
No
No
19
20
Integrating Your Website Using HTML
HTML Variables
3
Customising Your PayPal
Payment Page
You can customise the look and feel of the PayPal payment page in the following two ways:
Modifying Your PayPal Account Settings
N
OTE
: HTML variables will override the settings you save on your profile page.
Modifying Your PayPal Account Settings
In your Profile section on PayPal.com, you can change the look and feel of the payment page by modifying the settings on the following pages under the Website Payment Settings section.
21
22
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
Settings
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
This page allows you to select the information you want to collect and display on your payment page and where you want to display the payment confirmation.
Although we offer many options on this page, we recommend that you display as few options as possible on the payment page. For example, you may have already collected shipping address on your own website in order to calculate the shipping cost and passed it on to
PayPal's payment page. Therefore, it is not necessary to show this option on the payment page again.
You could have information that has already been collected on your website, but you may want to pass it to PayPal and display it on the hosted payment page again. This information will be pre-filled and editable on this page.
24
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
What information do you want to show on your PayPal Pro payment page?
You can select the fields that are displayed on your hosted payment page. You have the following options:
Card Information - Buyer's credit card information. This field is always displayed and selected by default.
Customer Name - Buyer's first and last name
Billing Address - Buyer's billing address
Billing Phone Number - Buyer's phone number
Billing Email Address - Buyer's email address
Shipping Address - Buyer's shipping address. This is required for seller protection. Ensure that you set the buyer's shipping address HTML variable if you do not select this box.
How do you want to display payment confirmation?
Once the transaction is successful, you can choose to display your payment confirmation on either a PayPal's confirmation page or on your own payment confirmation page.
On a PayPal page that shows the payment is complete - The payment confirmation appears on the PayPal confirmation page. Optionally, you can also provide a URL on the confirmation page to take your buyer back to your website. To do so, enter the appropriate
URL in the field provided.
On the Company's confirmation page - The payment confirmation will appear on your own payment confirmation page. For this, enter the URL of the page that will display the payment confirmation. You will have to message the outcome of the transaction to the buyer when PayPal redirects back to this URL. Be sure to display specifics of the order so the buyer sees a meaningful confirmation. You can get the specifics of the order using the
Transaction ID we pass back to you with the return URL.
Customisation
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
26
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
This page allows you to customise your payment page. You can customise the header, background, title, button, and the order summary column of your payment page.
PayPal offers three design templates for you to choose. Template A is the default template, however, you can choose from any of the templates offered.
N
OTE
: Your buyers will not see the payment page until you have completed the HTML integration with your website.
Preview the design of your payment page. You can either change the design of your template, or select and customise a different template on this page. To make changes, left-click on the section you are trying to modify or the corresponding Click to Edit button for that section. On the pop-up that appears, click the color selector to change the color, or enter the appropriate
URL, as needed.
If the buyer pays by logging into PayPal, the look and feel of that flow can be customised through the Website Payment Standard customisation options on the Profile page.
After making the changes, click one of the following buttons:
Preview - Preview the changes you have made to your template before saving and publishing it.
Save and Publish - Save all the changes you have made and publish the updated template.
Your buyers will see the updated payment page.
Cancel - Discard all the changes you have made in this session.
Previous Version - Discard all changes you have made since the last time you saved the template. Your buyers will see the last saved template.
N
OTE
: You must make all modifications (including changing templates) within the same session, otherwise all changes will be lost and you will have to redo your changes. If the session times out, the design of the template will remain at the version that was last published.
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
Choosing a Template
Choose from the following three design templates:
Template A. Selected by default - you can customise the header.
F IGURE 3.1 Template A
28
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
Template B. Customise the header, background, title, button, and the order summary column.
F IGURE 3.2 Template B
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
Template C. Customise the header, background, title, and the button.
F IGURE 3.3 Template C
30
Customising Your PayPal Payment Page
Modifying Your PayPal Account Settings
Customising Your Template
Consider the following when you customise your template:
Header (applicable to Template A, B, and C) - By default, the business name from your profile is shown in the header. You can change the following:
– Header height and color
– Font type, size, and color
– Swap between displaying the business name or the business logo image
– Position of the business name or the logo
N
OTE
: We recommend that you host your images on a secure server (https://) to avoid the security dialog window that may hurt conversion.
Background (applicable to Template B and C) - You can change the following:
– Background color
– Background image URL
Title and Button (applicable to Template B and C) - You can change the following:
– Header color
– Title bar color and title text color
– Button color and button text color
Order Summary Column (applicable to Template C) - You can change the following:
– Column color
– Image URL
Customising Your PayPal Payment Page
Adding HTML Variables
Adding HTML Variables
The table below lists the PayPal Pro HTML variables you can use to customise the look and feel of your payment page.
N
OTE
: The values you pass must not contain any of these special characters (){}<>\";
T ABLE 3.1 HTML Variables for Look and Feel of Payment Page
Variable bodyBgColor bodyBgImg footerTextColor headerBgColor headerHeight logoFont logoFontColor logoFontSize logoImage logoImagePosition logoText orderSummaryBgColor orderSummaryBgImage pageButtonBgColor pageButtonTextColor pageTitleTextColor sectionBorder
Description
Color of the surrounding background of the payment page.
Image of the surrounding background of the payment page. The file extension can be .gif, .jpg, .jpeg, or .png format.
Color of the footer text.
Color of the header background.
Height of the header banner. It can be from 50 to 140 pixels. The width cannot be changed. It is always 940 pixels.
Font type of the logo text.
Color of the logo text.
Font size of the logo text.
Image displayed in the logo. The acceptable file extension formats are .gif, .jpg, .jpeg, or .png. The width of the image cannot be more than 940 pixels.
Position of the image in the logo.
Business name displayed on your profile page. This field is editable and text specified here is displayed on the header if logoImage is not specified.
Color of the Order Summary column on the right side of the payment page. You cannot change the color of the Order Summary box.
Background image you can put in the Order Summary Column. The acceptable file extension formats are .gif, .jpg, .jpeg, or .png.
Background color of the Pay Now button.
Color of the Pay Now button. You cannot change the text of the button.
Color of the text used in the title of the page. (Text that says “Choose a way to pay.”)
Background of the section that displays “Pay with my PayPal account” or “Pay with a Card”.
32
Customising Your PayPal Payment Page
Adding HTML Variables
T ABLE 3.1 HTML Variables for Look and Feel of Payment Page
Variable showCustomerName showBillingAddress showBillingPhone showBillingEmail showHostedThankyouPage showShippingAddress subheaderText template
Description
Display customer name (first name and last name).
Default Value: true
Allowable Value: true or false, where true = show and false = hide.
Display billing address information.
Default Value: true
Allowable Value: true or false, where true = show and false = hide.
Display billing phone number.
Default Value: true
Allowable Value: true or false, where true = show and false = hide.
Display email address for billing purposes.
Default Value: false
Allowable Value: true or false, where true = show and false = hide.
Display PayPal’s confirmation page.
Default Value: true
Allowable Value: true or false, where true = show and false = hide.
Display shipping address.
Default Value: false
Allowable Value: true or false, where true = show and false = hide.
Color of the “Pay with my PayPal account” or “Pay with a Card” text.
Template used for your payment page. Options are TemplateA,
TemplateB, and TemplateC. TemplateD is used for iFrame integration only and is not an option on the Customization page on
PayPal.com.
4
Integrating iFrame in Your
Website
PayPal offers a compact payment form that can be integrated in an iFrame on your website.
Since this form is integrated on your website, the buyer never leaves your website, thereby reducing potential drop-offs. You can also maintain your checkout look and feel in the master frame that surrounds the compact payment form. The credit card fields are part of the compact payment form so you do not have to collect this information separately.
IMPORTANT: Due to security concerns involving iFrame, the following browsers are supported and secure to use - Internet Explorer 7.0, 8.0 and 9.0, Firefox 8,
Chrome 4 and 4.1, Safari 4.x and 5.x. Transactions involving users of other browsers should not use the iFrame flow or abandon the transaction.
Additionally, there is another risk beyond the iFrame flow - should the
PayPal iFrame become the source of an attack, it would appear that the attack is originating from the merchant site; do not use the iFrame flow if you wish to avoid this additional risk.
N
OTE
: Due to spoof concerns, the form does not contain any PayPal branding.
The compact payment form contains the following fields:
Credit card number
Expiry date
CVV2 number (if applicable, based on the card type)
Any additional fields required for other card types, such as start date and issue number for
Maestro or Switch.
The form also offers the following options:
Remove the Pay with PayPal button. Although the form offers the option to pay using
PayPal account by default, you can contact your account manager or customer support to turn this option off.
Manually customize the color of the Pay Now button.
IMPORTANT: The compact payment form does not display the buyer's billing address, even if showBillingAddress=true is passed. However, for some merchants, it may be necessary to pass the billing address to successfully process the transactions.
34
Integrating iFrame in Your Website
Integrating iFrame
Integrating iFrame
Choose one of the following methods to integrate the compact payment form in your website:
IMPORTANT: For optimal performance, PayPal recommends that you load the iFrame asset before other assets such as images and JavaScripts. If there are too many assets running on your payment page when you load iFrame, the request for the iFrame may not be placed or might get delayed. This may result in the buyers seeing a blank iFrame.
Manual Integration
To manually integrate the compact payment form in your website, perform the following steps:
1. Enter the iFrame tag at the location where you want the compact payment form to appear on your website. For example:
<iframe name="hss_iframe" width="570px" height="540px"></iframe>
The allowable size for the compact payment form is 570 pixels in width to 540 pixels in height.
2. Below is the iFrame code, add the hidden form that is populated with the appropriate
PayPal Pro variables (including the total amount to be paid) and specify the variable
TemplateD
. For example,
<form style="display:none" target="hss_iframe" name="form_iframe" method="post" action="https://securepayments.paypal.com/cgi-bin/acquiringweb">
<input type="hidden" name="cmd" value="_hosted-payment">
<input type="hidden" name="subtotal" value="50">
<input type="hidden" name="business" value="HNZ3QZMCPBAAA">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="template" value="templateD">
<input type="hidden" name="return" value="https://yourwebsite.com/receipt_page.html">
</form>
N
OTE
: If the iFrame transactions fail, pass the billing address
Integrating iFrame in Your Website
Integrating iFrame
3. Ensure that the target name matches the iFrame name, as highlighted in the example below:
<iframe name="hss_iframe" width="570px" height="540px"></iframe>
<form style="display:none" target="hss_iframe" name="form_iframe" method="post" action="https://securepayments.paypal.com/cgi-bin/acquiringweb">
4. Submit the form using JavaScript. For example:
<script type="text/javascript">
document.form_iframe.submit();
</script>
Example of Manual Integration
The complete example as per the above steps is as follows:
<iframe name="hss_iframe" width="570px" height="540px"></iframe>
<form style="display:none" target="hss_iframe" name="form_iframe" method="post" action="https://securepayments.paypal.com/cgi-bin/acquiringweb">
<input type="hidden" name="cmd" value="_hosted-payment">
<input type="hidden" name="subtotal" value="50">
<input type="hidden" name="business" value="HNZ3QZMCPBAAA">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="template" value="templateD">
<input type="hidden" name="return" value="https://yourwebsite.com/receipt_page.html">
</form>
<script type="text/javascript">
document.form_iframe.submit();
</script>
API Integration
To integrate the compact payment form in your website using the API, refer to
Button Manager API with PayPal Pro Checkout” on page 40
.
N
OTE
: Use template=templateD for this type of integration.
There are two options in the response to initiate the PayPal Pro payment flow:
Using URL Returned in the Response
35
36
Integrating iFrame in Your Website
Integrating iFrame
Using URL Returned in the Response
In the URL identified in the response as EMAILLINK, add “src” for iFrame as per the example below to redirect the buyer and initiate the payment flow.
<iframe src="https://www.paypal.com/...?hosted_button_id=HSS-.." width="570px" height="540px"></iframe>
The allowable size of the compact payment form is 570 pixels in width to 540 pixels in height.
IMPORTANT: This option is not supported by Safari browsers. Use the Form POST option described below.
Using Form POST
Identify the WEBSITECODE in the response and use the code to create a Pay Now button on your review page. When your buyer clicks the button, they are redirected to the PayPal hosted payment page. Like the URL, the button is usable for approximately two hour or until the payment is successful.
1. Enter the iFrame tag at the location where you want the compact payment form to appear on your website. For example:
<iframe name="hss_iframe" width="570px" height="540px"></iframe>
The allowable size for the compact payment form is 570 pixels in width to 540 pixels in height.
2. Insert the following in the iFrame tag:
WEBSITECODE=<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="HSSbXkpgPTNgZi7CyfIwWTAkWPSDbKziokU">
<input type="image" src="https://www.paypal.com/i/btn/btn_paynow_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypal.com/i/scr/pixel.gif" width="1" height="1">
</form>
3. Submit the form using JavaScript. For example:
<script type="text/javascript">
document.form_iframe.submit();
</script>
Integrating iFrame in Your Website
Integrating iFrame
Example of API (Form POST) Integration
The complete example as per the above steps is as follows:
<iframe name="hss_iframe" width="570px" height="540px"></iframe>
WEBSITECODE=<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="HSSbXkpgPTNgZi7CyfIwWTAkWPSDbKziokU">
<input type="image" src="https://www.paypal.com/i/btn/btn_paynow_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypal.com/i/scr/pixel.gif" width="1" height="1">
</form>
<script type="text/javascript">
document.form_iframe.submit();
</script>
37
38
Integrating iFrame in Your Website
Integrating iFrame
5
Integrating Your Website Using
API
Using the Button Manager API, you can programmatically create the checkout button that initiates the PayPal Pro checkout flow on your website. You create the checkout button dynamically when the buyer attempts to checkout on your website. When the buyer clicks on your checkout button, you call the BMCreateButton API operation to create a checkout button and display it on your web page. When the buyer clicks on this checkout button, he or she is redirected to the PayPal payment page where he or she can complete the payment.
HTML variables control the presentation of the PayPal payment pages, the information contained on the pages, and pages to which your buyer can be returned to when leaving the payment pages. For a list of HTML variables, refer to
For complete information on the Button Manager API, refer to the Button Manager API (NVP) or Button Manager API (SOAP) .
N
OTE
: Using the Button Manager API, you can programmatically create the checkout button, but not manage, edit, or delete it.
Button Hosting
For PayPal Pro, using BUTTONTYPE=PAYMENT, you can create the following kinds of checkout buttons:
Token buttons (BUTTONCODE=TOKEN) are not stored on PayPal. They are dynamic and initiate the PayPal Pro checkout flow. The parameters associated with this kind of button are secure. They have a lifetime of approximately two hours, if not used.
Encrypted buttons (BUTTONCODE=ENCRYPTED) are not stored on PayPal. The parameters associated with this kind of button are encrypted. You must update the web pages that use an encrypted button each time the button or the associated information changes.
Clear text buttons (BUTTONCODE=CLEARTEXT) are not stored on PayPal. The parameters associated with this kind of button are not encrypted. They can be used dynamically because you can change the value of a parameter anytime. However, if you use them, recognize the risk that sensitive information can be altered or stolen.
N
OTE
: Hosted buttons (BUTTONCODE=HOSTED) are not supported for PayPal Pro and will return an error if used.
For more information about Button Manager API usage, refer to
.
Integrating Your Website Using API
Using the Button Manager API with PayPal Pro Checkout
Using the Button Manager API with PayPal Pro Checkout
To create a checkout button on your website, you call the BMCreateButton API operation.
When the buyer clicks on the checkout button, PayPal initiates the PayPal Pro checkout flow.
You must decode the response from the BMCreateButton API. For information about URL encoding, refer to the Name-Value Pair API Developer Guide .
There are two options in the response to initiate the PayPal Pro payment flow:
Using URL Returned in the Response (Recommended)
Using URL Returned in the Response (Recommended)
40
Using the URL identified in the response as EMAILLINK, you can redirect the buyer and initiate the payment flow.
Example of TOKEN
EMAILLINK=https://www.paypal.com/cgi-bin/webscr?cmd=_sxclick&hosted_button_id=HSS-
2MTCOLOp9LoPGdFYsYclhbGyjJVNrMHO&HOSTEDBUTTONID=HSS-
2MTCOLOp9LoPGdFYsYclhbGyjJVNrMHO&TIMESTAMP=2010-09-
15T00:30:35Z&CORRELATIONID=2fc9a340a2356&ACK=Success&VERSION=65.0&BUILD=150
0269
Integrating Your Website Using API
Using the Button Manager API with PayPal Pro Checkout
Example of ENCRYPTED
EMAILLINK=https://www.paypal.com/acquiringweb?cmd=_hostedpayment&business=idc%2dautomation%2duk%2dpro%2dt1%40paypal%2ecom&tax=2&ship ping=3&business=K5HHZSMWMCN58&subtotal=11&handling=4&TIMESTAMP=2010-09-
15T00:39:06Z&CORRELATIONID=23d12ce1161f2&ACK=Success&VERSION=65.0&BUILD=150
0269
Example of CLEARTEXT
EMAILLINK=https://www.paypal.com/acquiringweb?cmd=_hostedpayment&business=idc%2dautomation%2duk%2dpro%2dt1%40paypal%2ecom&tax=2&ship ping=3&business=K5HHZSMWMCN58&subtotal=11&handling=4&TIMESTAMP=2010-09-
15T00:40:32Z&CORRELATIONID=64553e7c7c84&ACK=Success&VERSION=65.0&BUILD=1500
269
The button variables control the presentation in the flow and the information that is provided to the buyer initially. Because the URL is associated with a PayPal Pro token, the URL is usable for approximately two hours after it is created or until the payment is successful.
Using Form POST
Identify the WEBSITECODE in the response and use the code to create a Pay Now button on your review page. When your buyer clicks the button, they are redirected to the PayPal hosted payment page. Like the URL, the button is usable for approximately two hours or until the payment is successful.
41
42
Integrating Your Website Using API
Using the Button Manager API with PayPal Pro Checkout
Example for TOKEN
WEBSITECODE=<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="HSS-
2MTCOLOp9LoPGdFYsYclhbGyjJVNrMHO">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_auto_billing_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypal.com/en_GB/i/scr/pixel.gif" width="1" height="1">
</form>
Example for ENCRYPTED
WEBSITECODE=<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="encrypted" value="BEGIN PKCS7......END PKCS7">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_auto_billing_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypal.com/en_GB/i/scr/pixel.gif" width="1" height="1">
</form>
Example of CLEARTEXT
WEBSITECODE=<form action="https://www.paypal.com/acquiringweb" method="post">
<input type="hidden" name="cmd" value="_hosted-payment">
<input type="hidden" name="business" value="[email protected]">
<input type="hidden" name="tax" value="2">
<input type="hidden" name="shipping" value="3">
<input type="hidden" name="business" value="K5HHZSMWMCN58">
<input type="hidden" name="subtotal" value="11">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="handling" value="4">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_auto_billing_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online.">
<img alt="" border="0" src="https://www.paypal.com/en_GB/i/scr/pixel.gif" width="1" height="1">
</form>
Integrating Your Website Using API
Using the Button Manager API with PayPal Pro Checkout
N
OTE
: The PayPal payment page displays a button identified as Pay Now to complete the checkout flow. The Pay Now button on the PayPal page is different than the Pay Now button created by the BMCreateButton API operation on the review page. You may need to change the URL for the latter in BUTTONIMAGEURL to avoid confusion.If a
URL is not specified in BUTTONIMAGEURL, then the default Pay Now is used for the button.
Encrypting Buttons Using Public and Private Key
Using Encrypted Website Payments helps secure payment buttons that you generate or write manually. Encrypted Website Payments protects the HTML button code that contains pricing information by encrypting it. HTML button code that you protect by using Encrypted Website
Payments cannot be altered by malicious third parties to create fraudulent payments. For
detailed information, refer to Chapter 8, “Protecting Buttons by Using Encrypted Website
Example of Initiating PayPal ProCheckout
The example shows the NVP parameters using BUTTONCODE=TOKEN for creating a URL to initiate the PayPal Pro checkout flow.
...
BUTTONCODE=TOKEN
BUTTONTYPE=PAYMENT
BUTTONIMAGEURL=https://www.paypal.com/en_US/i/btn/btn_billing.gif
L_BUTTONVAR0=subtotal=11
L_BUTTONVAR1=tax=2
L_BUTTONVAR2=shipping=3
L_BUTTONVAR3=handling=4
L_BUTTONVAR4=first_name=Bob
L_BUTTONVAR5=last_name=Jones
L_BUTTONVAR6=address1=Gardens
L_BUTTONVAR7=address2=99343
L_BUTTONVAR8=city=Paris
L_BUTTONVAR9=state=Alsace
L_BUTTONVAR10=zip=75002
L_BUTTONVAR11=country=FR
L_BUTTONVAR12=billing_first_name=BobBilling
L_BUTTONVAR13=billing_last_name=JonesBilling
L_BUTTONVAR14=billing_address1=5088 - 061 Craven Hill Gardens
L_BUTTONVAR15=billing_address2=Apt# 199343
L_BUTTONVAR16=billing_city=Wolverhampton
L_BUTTONVAR17=billing_state=West Midlands
L_BUTTONVAR18=billing_zip=W12 4LQ
L_BUTTONVAR19=billing_country=GB
L_BUTTONVAR20=night_phone_a=408
L_BUTTONVAR21=night_phone_b=398
L_BUTTONVAR22=night_phone_c=3065
43
44
Integrating Your Website Using API
Using the Button Manager API with PayPal Pro Checkout
L_BUTTONVAR23=notify_url=www.yourcompany.com
L_BUTTONVAR24=custom=custom1
L_BUTTONVAR25=cancel_return=http://www.cancel_return.com
L_BUTTONVAR26=paymentaction=sale
L_BUTTONVAR27=currency_code=GBP
L_BUTTONVAR28=invoice=123456789
L_BUTTONVAR29=lc=GB
L_BUTTONVAR30=showBillingAddress=false
L_BUTTONVAR31=showShippingAddress=false
L_BUTTONVAR32=showBillingEmail=true
L_BUTTONVAR33=showBillingPhone=true
L_BUTTONVAR34=showCustomerName=true
L_BUTTONVAR35=showCardInfo=true
L_BUTTONVAR36=showHostedThankyouPage=true
L_BUTTONVAR37=bn=GBD
L_BUTTONVAR38=cbt=Merchant ABCD
L_BUTTONVAR39=address_override=false
L_BUTTONVAR40=cpp_header_image=Red
L_BUTTONVAR41=logoText=YourCompanyLogo
L_BUTTONVAR42=logoImage=http://yourcompanyimages.com/logo.gif
L_BUTTONVAR43=logoImagePosition=center
L_BUTTONVAR44=logoFont=Arial Bold
L_BUTTONVAR45=logoFontSize=24px
L_BUTTONVAR46=logoFontColor=#f0ff0f
L_BUTTONVAR47=bodyBgImg=sdf
L_BUTTONVAR48=bodyBgColor=#AEAEAE
L_BUTTONVAR49=headerHeight=70px
L_BUTTONVAR50=headerBgColor=#4B6BA1
L_BUTTONVAR51=PageTitleTextColor=Blue
L_BUTTONVAR52=PageCollapseBgColor=Blue
L_BUTTONVAR53=PageCollapseTextColor=Yellow
L_BUTTONVAR54=PageButtonBgColor=Blue
L_BUTTONVAR55=PageButtonBgColor=Blue
L_BUTTONVAR56=orderSummaryBgColor=#EDF2F7
L_BUTTONVAR57=orderSummaryBgImage=http://teamworks/scr_bg_ordersummary.jpg
L_BUTTONVAR58=footerTextColor=#333333
L_BUTTONVAR59=footerTextlinkColor=#00f00f
L_BUTTONVAR60=template=templateC
L_BUTTONVAR61=return=http://www.yourcompany.com
Integrating Your Website Using API
BMCreateButton API Operation
BMCreateButton API Operation
Use the BMCreateButton API operation to create PayPal Pro checkout button.
BMCreateButton Request
The request fields specify the characteristics of your button, which include associated menu items related to the button. You can specify up to 5 menu items, each of which can include up to 10 possible selections.
BMCreateButton Request Fields
Field
METHOD
N
OTE
: The values you pass must not contain any of these special characters (){}<>\";
Description
BUTTONCODE
BUTTONTYPE
L_BUTTONVAR n
(Required)
BMCreateButton
(Optional) The kind of button code to create. It is one of the following values:
TOKEN
- A secure button, not stored on PayPal, used only to initiate the
PayPal Pro checkout flow; default for Pay Now button. Since version 65.2
ENCRYPTED
- An encrypted button, not stored on PayPal
CLEARTEXT
- An unencrypted button, not stored on PayPal
(Required) The kind of button you want to create.
PAYMENT
- Pay Now button; since version 65.2
(Optional) HTML standard button variables
45
46
Integrating Your Website Using API
BMCreateButton API Operation
BMCreateButton Response
The response contains an ID if the button is hosted on PayPal, and code for HTML in a website and for a link in email.
BMCreateButton Response Fields
Field
WEBSITECODE
EMAILLINK
HOSTEDBUTTONID
Description
HTML code for web pages
Code for URL for the PayPal Pro checkout flow
ID of a PayPal Pro token
BMCreateButton Errors
11925
11926
11927
11928
Error
Code
10001
11923
11924
11929
11931
11932
11933
Short Message
Internal Error
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Data
Invalid Argument
Invalid Argument
Invalid Data
Invalid Argument
Invalid Data
Invalid Data
Long Message
Internal Error
The button image value specified is invalid.
The button image URL specified is invalid.
The button type specified is invalid.
One of the parameters specified using
ButtonVar is invalid.
The buy now button text specified is invalid.
The email or merchant ID specified is invalid.
A cart button must have an item name and amount specified.
The subscription button text specified is invalid.
You must specify a corresponding number of entries for option names and selections.
You cannot skip index numbers for option selections. Option selections must be specified sequentially.
Correcting This Error...
Integrating Your Website Using API
BMCreateButton API Operation
Error
Code
11934
11936
11937
11938
11940
11941
11942
11943
11945
11947
Short Message
Invalid Data
Invalid Data
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Data
Invalid Argument
11948 Invalid Argument
12210
13117
13118
13119
13120
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Argument
Invalid Argument
Long Message
You must specify the same number of entries for option prices and selections.
You cannot specify both an item price and prices for individual selections within an option.
A text box name specified is invalid. Text box names must not exceed 64 characters.
The button code value specified is invalid.
An option name specified is invalid.
Option names must not exceed 64 characters.
An option selection value specified is invalid. Option selection values must not exceed 64 characters.
An option price value specified is invalid.
Make sure any punctuation marks are in the correct places.
The button country value specified is invalid.
The button country and language code combination specified is invalid.
The tax rate specified is invalid. Make sure any punctuation marks are in the correct places and value specified is in the range 0.0 to 100.
The amount specified is invalid. Make sure any punctuation marks are in the correct places.
The currency code value specified is invalid.
Subtotal amount is not valid.
Tax amount is not valid.
Handling amount is not valid.
Shipping amount is not valid.
Correcting This Error...
47
48
Integrating Your Website Using API
BMCreateButton API Operation
6
Testing Your Integration in
Sandbox
The PayPal Sandbox is a self-contained environment within which you can prototype and test
PayPal features. The PayPal Sandbox is an almost identical copy of the live PayPal website.
Its purpose is to give developers a shielded environment for testing and integration purposes, and to help avoid problems that might occur while testing PayPal integration solutions on the live site. Before moving any PayPal-based application into production, you should test the application in the Sandbox to ensure that it functions as you intend and within the guidelines and standards set forth by the PayPal Developer Network (PDN).
For complete details on using Sandbox, refer to Sandbox User Guide .
Creating a Preconfigured Account
When you log in to the Sandbox, the Sandbox Test Environment home page appears, as shown below:
49
50
Testing Your Integration in Sandbox
Creating a Preconfigured Account
To test your PayPal Pro integration, create a preconfigured account using the following steps:
1. On the Sandbox Home page, under the Test Accounts section, and click Create a
preconfigured buyer or seller account.
2. The Create a Sandbox Test Account page appears, as shown below:
Testing Your Integration in Sandbox
Creating a Preconfigured Account
3. Choose Italy from the Country drop-down menu.
4. Select Website Payments Pro as the Account Type.
5. The Login Email and Password fields are pre-filled. The rest of the fields are optional so make the appropriate selections or accept the defaults.
N
OTE
: Make a note of the password as you will need it to log into the Sandbox Test Site.
6. Click Create Account. The following page confirms the creation of the test account:
N
OTE
: The login email is a pseudo-randomized address, which is based on the address you specified. Credit card and bank account numbers are also generated randomly, which are displayed when you click View Details.
7. Ensure that Payment Review is set to Enabled. In doing so, all transactions on this account are put into pending review state. You can then click accept or decline on the Transaction
Details page to simulate the fraud agent’s action.
Testing Your Integration in Sandbox
Creating a Preconfigured Account
8. Click Enter Sandbox Test Site. The Sandbox Test Site appears in a different browser window, as shown below. If you are not automatically logged in to the Sandbox Test Site, log in using the email address created for the test account as part of step 6 and the password you noted in step 5.
52
You are ready to test your PayPal Pro integration on the Sandbox Test Site.
Testing Your Integration in Sandbox
Testing Your Integration and Settings
Testing Your Integration and Settings
The following sections contain information for testing your integration and modifying the look and feel of your payment page in the Sandbox environment.
Testing Your Integration
To test your integration in the Sandbox environment, follow the steps specified in “Simple
PayPal Pro Integration” on page 15 . For testing purposes, you must make the following
changes in the Form POST:
1. Change the URL to point to the Sandbox environment.
From:
<form action="https://securepayments.paypal.com/acquiringweb" method="post">
<input type="hidden" name="cmd" value="_hosted-payment"> to:
<form action="https://securepayments.sandbox.paypal.com/acquiringweb" method="post">
<input type="hidden" name="cmd" value="_hosted-payment">
2. Change the business value to the Secure Merchant ID value that is specified at the top of the Profile page of the Sandbox Test Site.
Accordingly, the Form POST for testing purposes will be:
<form action="https://securepayments.sandbox.paypal.com/acquiringweb" method="post">
<input type="hidden" name="cmd" value="_hosted-payment">
<input type="hidden" name="subtotal" value="50">
<input type="hidden" name="business" value="HNZ3QZMCPBAAA">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="return" value="https://yourwebsite.com/receipt_page.html">
<input type="submit" name="METHOD" value="Pay Now">
</form>
54
Testing Your Integration in Sandbox
Testing Your Integration and Settings
Testing Your Settings
To change the look and feel of your payment page, modify the settings of the Customisation and Settings pages in the Profile section of the Sandbox Test Site. For complete details, refer to
“Modifying Your PayPal Account Settings” on page 21 .
7
Order Processing
This chapter walks you through the end of end order processing experience. It includes information about verifying the status and authenticity of the order before fulfilling it.
Verifying Transaction Status and Authenticity
When the buyer successfully completes a transaction, they are redirected either to the PayPal confirmation page or a website you specified in the return variable or on the Settings page
in the Profile section (as outlined in “Simple PayPal Pro Integration” on page 15
). When the browser is redirected to the website you specified, a Transaction ID is appended to it.
When you receive the redirect (URL with Transaction ID), you must verify that the order was completed successfully on PayPal before sending the items to the buyer. You can do so by checking the confirmation email sent to you by PayPal or by verifying the transaction history.
You can also using one of the following methods:
Validate Instant Payment Notification (IPN)
IPN enables you to receive messages about transaction payments and activity from PayPal through asynchronous, server-to-server communication. This allows you to integrate your online payments with your order fulfillment process.
Through IPN, you receive messages for the following:
Payments and their status (pending, complete, or denied)
Fraud Management Filter actions
Recurring Payment activity
Authorisations, chargebacks, disputes, reversals, and refunds.
After a transaction has been processed, PayPal sends an IPN to the notification URL specified in your transaction using the parameter notify_url, or in your PayPal Profile. You must verify that the Transaction ID, transaction amount, and other order specific parameters such as
Invoice ID that are sent in the IPN match with the information you have in your order processing system. For more details, refer to Instant Payment Notification Guide .
55
56
Order Processing
Fulfilling Order
Execute a GetTransactionDetails API Call
Using GetTransactionDetails API, you can obtain information about a specific transaction.
If you are integrated with PayPal APIs, you can call GetTransactionDetails with the
Transaction ID that was returned in the web redirect to validate the authenticity of the order.
For complete details, refer to
“GetTransactionDetails API” on page 63 .
Fulfilling Order
After you have verified the authenticity of the payment amount and status, you can fulfil the order by shipping the item to the buyer.
N
OTE
: To benefit from PayPal’s Seller Protection, the item must be shipped to the address specified on the PayPal payment page or communicated to PayPal. Otherwise, the item is not eligible for Seller Protection. For more information, refer to
“Seller Protection” on page 11 .
8
Protecting Buttons by Using
Encrypted Website Payments
Using Encrypted Website Payments helps secure payment buttons that you generate or write manually. Encrypted Website Payments protects the HTML button code that contains pricing information by encrypting it. HTML button code that you protect by using Encrypted Website
Payments cannot be altered by malicious third parties to create fraudulent payments.
Encrypted Website Payments relies on standard public key encryption for protection. With public and private keys, you can dynamically generate HTML code for payment buttons and encrypt the payment details before displaying the buttons on your website. The below table illustrates the sequence of actions that occur with payment buttons protected by using
Encrypted Website Payments.
T ABLE 8.1 How Encrypted Website Payments Works
Website Actions
Generate a public key for the website, upload it to PayPal, and download the PayPal public certificate to the website.
N
OTE
: Do this action only once, when you first integrate
PayPal Pro with your website.
Generate HTML code for a payment button.
Encrypt the generated code by using the PayPal public key and then signing the encrypted code with the website’s private key.
Publish the signed, encrypted
HTML code for the payment button to the website
Buyer Action
Click the published PayPal payment button.
PayPal Action
Check the authenticity of the data by using the website’s public key, which was previously uploaded to
PayPal.
Decrypt the protected button code by using the PayPal private key.
Redirect the payer’s browser to the appropriate PayPal checkout experience, as specified in the
HTML variables of the decrypted button code.
58
Protecting Buttons by Using Encrypted Website Payments
Public Key Encryption Used by Encrypted Website Payments
Public Key Encryption Used by Encrypted Website Payments
Encrypted Website Payments uses public key encryption, or asymmetric cryptography, which provides security and convenience by allowing senders and receivers of encrypted communication to exchange public keys to unlock each others messages. The fundamental aspects of public key encryption are:
Public keys – Public keys are created by receivers and are given to senders before they encrypt and send information. Public certificates comprise a public key and identity information, such as the originator of the key and an expiry date. Public certificates can be signed by certificate authorities, who guarantee that public certificates and their public keys belong to the named entities.
You and PayPal exchange each others’ public certificates.
Private keys – Private keys are created by receivers are kept to themselves.
You create a private key and keep it in your system. PayPal keeps its private key on its system.
The encryption process – Senders use their private keys and receivers’ public keys to encrypt information before sending it. Receivers use their private keys and senders’ public keys to decrypt information after receiving it. This encryption process also uses digital signatures in public certificates to verify the sender of the information.
You use your private key and PayPal’s public key to encrypt your HTML button code.
PayPal uses it’s private key and your public key to decrypt button code after people click your payment buttons.
Setting Up Certificates Before Using Encrypted Website
Payments
Do the following before you use Encrypted Website Payments to protect your payment buttons:
Generating Your Private Key Using OpenSSL
Generating Your Public Certificate Using OpenSSL
Uploading Your Public Certificate to Your PayPal Account
Downloading the PayPal Public Certificate from the PayPal Website
PayPal uses only X.509 public certificates, not public keys. A public key can be used for decryption but contains no information identifying who provided the key. A public certificate includes a public key along with information about the key, such as when the key expires and who the key belongs to. PayPal accepts public certificates in OpenSSL PEM format from any established certificate authority, such as VeriSign.
You can generate your own private key and public certificate using open source software such as OpenSSL ( https://www.openssl.org
), which is detailed in the following section.
Protecting Buttons by Using Encrypted Website Payments
Setting Up Certificates Before Using Encrypted Website Payments
Generating Your Private Key Using OpenSSL
Using the openssl program, enter the following command to generate your private key. The command generates a 1024-bit RSA private key that is stored in the file my-prvkey.pem: openssl genrsa -out my-prvkey.pem 1024
Generating Your Public Certificate Using OpenSSL
The public certificate must be in PEM format. To generate your certificate, enter the following openssl command, which generates a public certificate in the file my-pubcert.pem: openssl req -new -key my-prvkey.pem -x509 -days 365 -out my-pubcert.pem
Uploading Your Public Certificate to Your PayPal Account
To upload your public certificate to your PayPal account:
1. Log in to your PayPal account at https://www.paypal.it
2. Click the Profile subtab.
3. In the Hosted Payment Settings column, click Website Payment Certificates.
The Website Payment Certificates page appears.
4. Scroll down the page to the Your Public Certificates section, and click the Add button.
The Add Certificate page appears.
5. Click Browse, and select the public certificate that you want to upload to PayPal from your local computer.
N
OTE
: The file you upload must be in PEM format.
6. Click Add.
After your public certificate is uploaded successfully, it appears in the Your Public
Certificates section of the Website Payment Certificates page.
7. Store the certificate ID that PayPal assigned to your public certificate in a secure place. You need the certificate ID that PayPal assigned to encrypt your payment buttons by using the
Encrypted Website Payments software provided by PayPal.
59
60
Protecting Buttons by Using Encrypted Website Payments
Setting Up Certificates Before Using Encrypted Website Payments
Downloading the PayPal Public Certificate from the PayPal Website
To download the PayPal public certificate:
1. Log in to your PayPal account at https://www.paypal.it
2. Click the Profile subtab.
3. In the Seller Preferences column, click the Encrypted Payment Settings link.
4. Scroll down the page to the PayPal Public Certificate section.
5. Click Download, and save the file in a secure location on your local computer.
Removing Your Public Certificate
IMPORTANT: If you remove your public certificate, its associated certificate ID is no longer valid for encrypting buttons, and any buttons that you generated or wrote manually for your website that use the ID will not function correctly.
To remove one or more of your public certificates:
1. Log in to your PayPal account at https://www.paypal.it
2. Click the Profile subtab.
3. In the Seller Preferences column, click the Encrypted Payment Settings link.
4. Scroll down the page to the PayPal Public Certificate section.
5. Select the radio button next to the certificate you want to remove, and click Remove.
The Remove Certificate page appears.
6. Click Remove to confirm the removal of the public certificate that you selected.
Protecting Buttons by Using Encrypted Website Payments
Setting Up Certificates Before Using Encrypted Website Payments
Using Encrypted Website Payments to Protect Your Payment Buttons
Encrypted Website Payments includes Java and Microsoft Windows software to protect the payment buttons that you generate or write manually. Download the software from the following location after logging in to PayPal: https://www.paypal.com/us/cgibin/webscr?cmd=p/xcl/rec/ewp-code
After you download and extract the software, copy your private key, public certificate, p12 file and the PayPal public certificate to the folder where the software is located.
1. Prepare an input file of PayPal Pro variables and values for each encrypted button that you want to generate. Each variable and value must be on a separate line, as in the following example.
N
OTE
: The cert_id variable identifies the public certificate you uploaded to PayPal website. cert_id=Z24MFU6DSHBXQ cmd=_xclick [email protected] item_number=1234 custom=sc-id-789 amount=500.00 currency_code=USD tax=41.25 shipping=20.00 address_override=true address1=123 Main St city=Austin state=TX zip=94085 country=US no_note=1 cancel_return=http://www.company.com/cancel.htm
2. Run the encryption software using the appropriate syntax, as shown below:
– Java: PPEncrypt CertFile PrivKeyFile PPCertFile InputFile
OutputFile [Sandbox]
– Microsoft Windows: java ButtonEncryption CertFile PKCS12File
PPCertFile Password InputFile OutputFile [Sandbox]
61
62
Protecting Buttons by Using Encrypted Website Payments
Setting Up Certificates Before Using Encrypted Website Payments where the argument is:
– CertFile: The pathname to your own public certificate
– PKCS12File: The pathname to the PKCS12-format of your own public certificate
– PPCertFile: The pathname to a copy of the PayPal public certificate
– Password: The passphrase to the PKCS12-format of your own public certificate
– InputFile: The pathname to file containing the non-encrypted Website Payments HTML
Form variables
– OutputFile: A file name for the encrypted output
– [Sandbox]: The optional word Sandbox that lets you test payment buttons in the PayPal
Sandbox that you protected with Encrypted Website Payments
3. Copy the encrypted code to your website.
Blocking Unprotected and Non-encrypted Website Payments
For extra security of your protected and encrypted buttons, update your PayPal account profile to block unprotected and non-encrypted payments.
To block payments from unprotected and non-encrypted Website Payments Standard buttons:
1. Log in to your PayPal account at https://www.paypal.it
2. Click the Profile subtab.
3. In the Seller Preferences column, click the Encrypted Payment Settings link.
4. Scroll down to the Encrypted Website Payments section.
5. Next to the Block Non-encrypted Website Payment label, select the On radio button.
6. Scroll to the bottom of the page, and click Save.
A
Optional API Operations
Using the Transaction ID, a number of PayPal API operations are available. The most commonly used for PayPal Pro are:
GetTransactionDetails API
Obtain information about a specific transaction.
GetTransactionDetails Response
GetTransactionDetails Request
T ABLE A.1 GetTransactionDetails Request Fields
Field
METHOD
TRANSACTIONID
Description
Must be GetTransactionDetails.
(Required) Unique identifier of a transaction.
N
OTE
: The details for some kinds of transactions cannot be retrieved withGetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example.
Character length and limitations - 17 single-byte alphanumeric characters.
63
64
Optional API Operations
GetTransactionDetails API
GetTransactionDetails Response
N
OTE
: All fields defined in the formal structure of GetTransactionDetails Response are not necessarily returned. Data is returned in a response only if PayPal has recorded data that corresponds to the field.
Payment Item Information Fields
Receiver Information Fields
T ABLE A.2 Receive Information Fields
Field
RECEIVERMAIL
RECEIVERID
Description
Primary email address of the payment recipient (the seller).
If you are the recipient of the payment and the payment is sent to your non-primary email address, the value of Receiver is still your primary email address.
Character length and limitations - 127 single-byte alphanumeric characters
Unique account ID of the payment recipient (the seller). This value is the same as the value of the recipient's referral ID.
Optional API Operations
GetTransactionDetails API
Payer Information Fields
T ABLE A.3 Payer Information Fields
Field
PAYERID
PAYERSTATUS
SHIPTOCOUNTRYCODE
PAYERBUSINESS
Description
Email address of payer.
Character length and limitations - 127 single-byte characters
Unique PayPal customer account identification number.
Character length and limitations - 13 single-byte alphanumeric characters.
Status of payer. Valid values are:
verified
unverified
Character length and limitations - 10 single-byte alphabetic characters.
Payer’s country of residence in the form of ISO standard 3166 twocharacter country codes.
Character length and limitations - Two single-byte characters
Payer’s business name.
Character length and limitations - 127 single-byte characters
Payer Name Fields
T ABLE A.4 Payer Name Fields
Field
SALUTATION
FIRSTNAME
MIDDLENAME
LASTNAME
Description
Payer’s salutation.
Character length and limitations - 20 single-byte characters
Payer’s first name.
Character length and limitations - 25 single-byte alphanumeric characters.
Payer’s middle name.
Character length and limitations - 25 single-byte alphanumeric characters.
Payer’s last name.
Character length and limitations - 25 single-byte alphanumeric characters.
66
Optional API Operations
GetTransactionDetails API
T ABLE A.4 Payer Name Fields
Field
SUFFIX
Description
Payer’s suffix.
Character length and limitations - 12single-byte alphanumeric characters.
Address Fields
T ABLE A.5 Address Fields
Field
ADDRESSOWNER
ADDRESSSTATUS
SHIPTONAME
SHIPTOSTREET
SHIPTOSTREET2
SHIPTOCITY
SHIPTOSTATE
SHIPTOZIP
SHIPTOCOUNTRYCODE
SHIPTOPHONENUMBER
SHIPTOPHONENUM
Description eBay company that maintains this address.
Valid values are:
eBay
PayPal
Status of street address on file with PayPal.
Valid values are:
none
Confirmed
Unconfirmed
Person’s name associated with this address
Character length and limitations - 32 single-byte characters.
First street address
Character length and limitations - 100 single-byte characters.
Second street address
Character length and limitations - 100 single-byte characters.
Name of the city
Character length and limitations - 100 single-byte characters.
State or province
Character length and limitations - 40 single-byte characters.
US zip code or other country-specific postal code.
Character length and limitations - 40 single-byte characters.
Expanded name of country
Character length and limitations - 20 single-byte characters.
Country code.
Character length and limitations - two single-byte characters.
Country code.
Character length and limitations - Two single-bye characters.
Optional API Operations
GetTransactionDetails API
Payment Information Fields
T ABLE A.6 Payment Information Fields
Field
TRANSACTIONID
PARENTTRANSACTIONID
RECEIPTID
TRANSACTIONTYPE
PAYMENTTYPE
ORDERTIME
AMT
CURRENCYCODE
Description
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Parent or related transaction identification number. This field is populated for the following transaction types:
Reversal - Capture of an authorised transaction.
Reversal - Reauthorisation of a transaction.
Capture of an order - The value of ParentTransactionID is the original OrderID.
Authorisation of an order - The value of ParentTransactionID is the original OrderID.
Capture of an order authorisation.
Void of an order - The value of ParentTransactionID is the original
OrderID.
Character length and limitations - 16 digits in xxxx-xxxx-xxxx-xxxx format
Receipt identification number
Character length and limitations - 16 digits in xxxx-xxxx-xxxx-xxxx format
The type of transaction
Valid values:
cart
express-checkout
Character length and limitations - 15 single-byte characters
Indicates whether the payment is instant or delayed.
Character length and limitations - Seven single-byte characters
Valid values:
none
echeck instant
Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.
The final amount charged, including any shipping and taxes from your
Merchant Profile.
Character length and limitations - Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
A three-character currency code.
68
Optional API Operations
GetTransactionDetails API
T ABLE A.6 Payment Information Fields
Field
FEEAMT
SETTLEAMT
TAXAMT
EXCHANGERATE
Description
PayPal fee amount charged for the transaction
Character length and limitations - Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Amount deposited in your PayPal account after a currency conversion.
Tax charged on the transaction.
Character length and limitations - Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account.
Character length and limitations - a decimal that does not exceed 17 characters, including decimal point.
Optional API Operations
GetTransactionDetails API
T ABLE A.6 Payment Information Fields
Field
PAYMENTSTATUS
Description
Status of the payment.
The status of the payment:
None - No status
Canceled-Reversal - A reversal has been canceled; for example, when you win a dispute and the funds for the reversal have been returned to you.
Completed - The payment has been completed, and the funds have been added successfully to your account balance.
Denied - You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element.
Expired - the authorisation period for this payment has been reached.
Failed - The payment has failed. This happens only if the payment was made from your customer’s bank account.
In-Progress - The transaction has not terminated, e.g. an authorisation may be awaiting completion.
Partially-Refunded - The payment has been partially refunded.
Pending - The payment is pending. See the PendingReason field for more information.
Refunded - You refunded the payment.
Reversed - A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element.
Processed - A payment has been accepted.
Voided - An authorisation for this transaction has been voided.
70
Optional API Operations
GetTransactionDetails API
T ABLE A.6 Payment Information Fields
Field
PENDINGREASON
REASONCODE
Description
N
OTE
: PendingReason is returned in the response only if
PaymentStatus is Pending.
The reason the payment is pending:
none - No pending reason.
address - The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving
Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the
Preferences section of your Profile.
authorisation - The payment is pending because it has been authorised but not settled. You must capture the funds first.
echeck - The payment is pending because it was made by an eCheck that has not yet cleared.
intl - The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.
multi-currency - You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.
order - The payment is pending because it is part of an order that has been authorised but not settled.
paymentreview - The payment is pending while it is being reviewed by PayPal for risk.
unilateral - The payment is pending because it was made to an email address that is not yet registered or confirmed.
verify - The payment is pending because you are not yet verified.
You must verify your account before you can accept this payment.
other - The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service.
The reason for a reversal if TransactionType is reversal:
none - No reason code
chargeback - A reversal has occurred on this transaction due to a chargeback by your customer.
guarantee - A reversal has occurred on this transaction due to your customer triggering a money-back guarantee.
buyer-complaint - A reversal has occurred on this transaction due to a complaint about the transaction from your customer.
refund - A reversal has occurred on this transaction because you have given the customer a refund.
other - A reversal has occurred on this transaction due to a reason not listed above.
Optional API Operations
GetTransactionDetails API
T ABLE A.6 Payment Information Fields
Field
PROTECTIONELIGIBILITY
Description
Since version 64.4, the kind of seller protection in force for the transaction, which is one of the following values:
Eligible – Seller is protected by PayPal's Seller Protection Policy for Unauthorised Payments and Item Not Received
ItemNotReceivedEligible – Seller is protected by PayPal's Seller
Protection Policy for Item Not Received
UnauthorizedPaymentEligible – Seller is protected by PayPal's
Seller Protection Policy for Unauthorized Payment
Ineligible – Seller is not protected under the Seller Protection
Policy
Payment Item Information Fields
T ABLE A.7 Payment Item Information Fields
Field
INVNUM
CUSTOM
NOTE
SALESTAX
Description
Invoice number you set in the original transaction.
Character length and limitations - 127 single-byte alphanumeric characters
Custom field you set in the original transaction.
Character length and limitations - 127 single-byte alphanumeric characters
Memo entered by your customer in PayPal Website Payments note field.
Character length and limitations - 255 single-byte alphanumeric characters
Amount of tax charged on payment.
72
Optional API Operations
GetTransactionDetails API
Payment Item Fields
T ABLE A.8 Payment Item Fields
Field
L_DESCn
L_NUMBERn
L_QTYn
L_AMTn
L_OPTIONSNAMEn
L_OPTIONSVALUEn
Description
Amount of tax charged on payment.
These parameters must be ordered sequentially beginning with 0 (for example L_DESC0, L_DESC1).
Item number set by you. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_number variable.
For example, item_number1, item_number2, and so forth.
Character length and limitations - 127 single-byte alphanumeric characters.
These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).
Quantity set by you or entered by the customer.
Character length and limitations - no limit
Cost of item.
These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).
PayPal option names for an item in the shopping cart; each name corresponds to an option value. There can be multiple option names per item.
The option names are ordered sequentially beginning with 0 (for example,L_OPTIONSNAMES0, L_OPTIONSNAME1).
PayPal option values corresponding to option names of an item in the shopping cart.
The option names are ordered sequentially beginning with 0 (for example,L_OPTIONSVALUE0, L_OPTIONSVALUE1).
Auction Fields
T ABLE A.9 Auction Fields
Field
BUYERID
CLOSINGDATE
MULTIITEM
Description
Customer’s auction ID
Auction’s close date
Counter used for multi-item auction payments
Optional API Operations
RefundTransaction API
Subscription Term Fields
T ABLE A.10 Subscription Terms Fields
Field
AMT
PERIOD
Description
The amount subscriber is to be charged in one payment.
Character length and limitations: no limit
The period of time that the subscriber will be charged.
Character length and limitations: no limit
RefundTransaction API
Issue a refund to the PayPal account holder associated with a transaction.
RefundTransaction Request
T ABLE A.11 RefundTransaction Request Fields
Field
METHOD
TRANSACTIONID
REFUNDTYPE
AMT
NOTE
Description
Must be RefundTransaction.
(Required) Unique identifier of a transaction.
Character length and limitations - 17 single-byte alphanumeric characters.
(Required) Type of refund you are making:
Other
Full
Partial
Refund amount. Amount is required if RefundType is Partial.
N
OTE
: If RefundType is Full, do not set the Amount.
(Optional) Custom memo about the refund.
Character length and limitations - 255 single-byte alphanumeric characters.
74
Optional API Operations
DoCapture API
RefundTransaction Response
T ABLE A.12 RefundTransaction Response Fields
Field
REFUNDTRANSACTIONID
FEEREFUNDAMT
GROSSREFUNDAMT
NETREFUNDAMT
Description
Unique transaction ID of the refund.
Character length and limitations - 17 single-byte alphanumeric characters.
Transaction fee refunded to original recipient of payment.
Amount of money refunded to original payer.
Amount subtracted from PayPal balance of original recipient of payment to make this refund.
DoCapture API
Capture an authorized payment.
DoCapture Request
T ABLE A.13 DoCapture Request Fields
Field
METHOD
AUTHORIZATIONID
AMT
CURRENCYCODE
Description
(Required) Must be DoCapture.
(Required) The authorisation identification number of the payment you want to capture.This is the transaction id returned from
DoExpressCheckoutPayment or DoDirectPayment.
Character length and limitations - 19 single-byte characters maximum.
(Required) Amount to capture.
Limitations - Value is a positive number which cannot exceed $10,000
USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
(Optional) A three-character currency code. Default: USD.
Optional API Operations
DoCapture API
T ABLE A.13 DoCapture Request Fields
Field
COMPLETETYPE
INVNUM
NOTE
Description
(Required) The value Complete indicates that this the last capture you intend to make.
The value NotComplete indicates that you intend to make additional captures.
N
OTE
: If Complete, any remaining amount of the original authorised transaction is automatically voided and all remaining open authorisations are voided.
Character length and limitations - 12 single-byte alphanumeric characters.
(Optional) Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history.
N
OTE
: This value on DoCapture will overwrite a value previously set on DoAuthorisation.
N
OTE
: The value is recorded only if the authorisation you are capturing is an order authorisation, not a basic authorisation.
Character length and limitations - 127 single-byte alphanumeric characters
(Optional) An informational note about this settlement that is displayed to the payer in email and in his transaction history.
Character length and limitations - 255 single-byte characters.
76
Optional API Operations
DoCapture API
T ABLE A.13 DoCapture Request Fields
Field
SOFTDESCRIPTOR
Description
(Optional) The soft descriptor is a per transaction description of the payment that is passed to the consumer’s credit card statement.
If a value for the soft descriptor field is provided, the full descriptor displayed on the customer’s statement has the following format:
<PP * | PAYPAL*><Merchant descriptor as set in the Payment
Receiving Preferences><1space><soft descriptor>
The soft descriptor can contain only the following characters.
Alphanumeric characters
- (dash)
* (asterisk)
. (period)
{space}
If you use any other characters (such as “,”), an error code is returned.
The soft descriptor does not include the phone number, which can be toggled between the merchant’s customer service number and PayPal’s customer service number.
The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8 characters are used by the PayPal prefix shown in the data format. Thus, the maximum length of the soft descriptor passed in the API request is:
22- len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
ReceivingPreferences> + 1)
For example, assume the following conditions:
The PayPal prefix toggle is set to PAYPAL* in PayPal’s admin tools.
The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card would be:
PAYPAL*EBAY JanesFlow
Optional API Operations
DoCapture API
DoCapture Response
N
OTE
: If you use version 56.0 or later of the DoCapture API,only the authorisation ID, transaction ID, transaction type, paymentdate, gross amount and payment status are guaranteed to be returned.If you need the values of other fields and they are not returned,you can obtain their values later by calling GetTransactionDetails or by using the reporting. mechanism.
DoCapture Response Fields
T ABLE A.14 DoCapture Response Fields
Field
AUTHORIZATIONID
Description
The authorisation identification number you specified in the request.
Character length and limitations - 19 single-byte characters maximum.
PayerInfo Type Fields
T ABLE A.15 PayerInfo Type Fields
Field
PAYERID
PAYERSTATUS
COUNTRYCODE
Description
Email address of payer.
Character length and limitations - 127 single-byte characters.
Unique PayPal customer account identification number.
Character length and limitations - 13 single-byte alphanumeric characters.
Status of payer. Valid values are:
verified
unverified
Character length and limitations - 10 single-byte alphabetic characters.
Payer’s country of residence in the form of ISO standard 3166 twocharacter country codes.
Character length and limitations - Two single-byte characters.
78
Optional API Operations
DoCapture API
T ABLE A.15 PayerInfo Type Fields
Field
BUSINESS
Description
Payer’s business name.
Character length and limitations - 127 single-byte characters.
Ship To Address Fields
T ABLE A.16 Ship To Address Fields
Field
ADDRESSSTATUS
SHIPTONAME
SHIPTOSTREET
SHIPTOSTREET2
SHIPTOCITY
SHIPTOSTATE
SHIPTOZIP
SHIPTOCOUNTRYCODE
Description
Status of street address on file with PayPal.
Valid values are:
none
Confirmed
Unconfirmed
Person’s name associated with this address.
Character length and limitations - 32 single-byte characters.
First street address.
Character length and limitations - 100 single-byte characters.
Second street address.
Character length and limitations - 100 single-byte characters.
Name of city.
Character length and limitations - 40 single-byte characters.
State or province.
Character length and limitations - 40 single-byte characters.
Required for U.S. addresses only.
U.S. ZIP code or other country-specific postal code.
Character length and limitations - 20 single-byte characters.
Country code.
Character length and limitations - Two single-byte characters.
Optional API Operations
DoCapture API
Payer Name Fields
T ABLE A.17 Payer Name Fields
Field
SALUTATION
FIRSTNAME
MIDDLENAME
LASTNAME
SUFFIX
Description
Payer’s salutation.
Character length and limitations - 20 single-byte characters.
Payer’s first name.
Character length and limitations - 25 single-byte characters.
Payer’s middle name.
Character length and limitations - 25 single-byte characters.
Payer’s last name
Character length and limitations - 25 single-byte characters.
Payer’s suffix
Character length and limitations - 12 single-byte characters.
80
Optional API Operations
DoCapture API
B
Moving from Website Payments
Standard to PayPal Pro
If you are moving from Website Payment Standard to PayPal Pro, you must make the following changes:
1. In the FORM tag, change the cmd value in the action attribute from:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick"> to:
<form action="https://securepayments.paypal.com/acquiringweb?cmd=_hostedpayment" method="post"><input type="hidden" name="cmd" value="_hostedpayment">
2. Change HTML variable amount to subtotal
.
N
OTE
: Website Payment Standard has separate values for amount
and quantity
, whereas PayPal Pro uses subtotal only. Ensure that the subtotal includes the amount you want to charge the buyer, taking into account any applicable discount and the quantity of items.
3. If you have already customised your checkout flow, such as color and background, you will need to redo those settings for PayPal Pro. For more information about customising the
look and feel of your payment page, refer to Chapter 3, “Customising Your PayPal
.
81
82
Moving from Website Payments Standard to PayPal Pro
Sample Code Comparison
Below is a comparison of Website Payment Standard code and PayPal Pro code.
N
OTE
: In the samples below, note that for Website Payment Standard, amount
and quantity are specified as 10 and 2 respectively. For PayPal Pro, the subtotal
is 20, which is the product of the above-mentioned amount
and quantity
. This is highlighted in bold below.
Sample Website Payments Standard Code
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="[email protected]">
<input type="hidden" name="amount" value="10">
<input type="hidden" name="quantity" value="2">
<input type="hidden" name="tax" value="1">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name=" invoice" value="MEM32507725">
<!-- Enable override of payer’s stored PayPal address. -->
<input type="hidden" name="address_override" value="1">
<!-- Set prepopulation variables to override stored address. -->
<input type="hidden" name="first_name" value="John">
<input type="hidden" name="last_name" value="Doe">
<input type="hidden" name="address1" value="345 Lark Ave">
<input type="hidden" name="city" value="San Jose">
<input type="hidden" name="state" value="CA">
<input type="hidden" name="zip" value="95121">
<input type="hidden" name="country" value="US">
<input type="hidden" name="bn" value="CC_Partner_WPS">
<input type="hidden" name="notify_url" value="https://www.paypal.com/IPN/">
<input type="image" name="submit" border="0" src="https://www.paypal.com/img.gif ">
</form>
Sample
PayPal Pro
Code
<form action=”https://securepayments.paypal.com/acquiringweb?cmd=_hostedpayment” method="post"><input type="hidden" name="cmd" value="_hostedpayment">
<input type="hidden" name="business" value="HNZ3QZMCPBAAA">
<input type="hidden" name="subtotal" value="20">
<input type="hidden" name="paymentaction" value="sale">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="invoice" value="MEM32507725">
<input type="hidden" name="template" value=”TemplateB">
<!-- Enable override of payer’s stored PayPal address. -->
<input type="hidden" name="address_override" value="true">
<input type="hidden" name="showShippingAddress" value="false">
<!-- Set prepopulation variables to override stored address. -->
<input type="hidden" name="first_name" value="John">
<input type="hidden" name="last_name" value="Doe">
<input type="hidden" name="address1" value="345 Lark Ave">
Moving from Website Payments Standard to PayPal Pro
<input type="hidden" name="city" value="San Jose">
<input type="hidden" name="state" value="CA">
<input type="hidden" name="zip" value="95121">
<input type="hidden" name="country" value="US">
<input type="hidden" name="billing_first_name" value="John">
<input type="hidden" name=" billing_last_name" value="Doe">
<input type="hidden" name=" billing_address1" value="345 Lark Ave">
<input type="hidden" name=" billing_city" value="San Jose">
<input type="hidden" name=" billing_state" value="CA">
<input type="hidden" name=" billing_zip" value="95121">
<input type="hidden" name=" billing_country" value="US">
<input type="hidden" name="bn" value="CC_Partner_H3S">
<input type="hidden" name="notify_url" value="https://www.paypal.com/IPN/">
<input type="image" name="submit" border="0" src="https://www.paypal.com/img.gif ">
</form>
84
Moving from Website Payments Standard to PayPal Pro
C
Error Messages
The table below lists error codes and the appropriate correction action.
T ABLE C.1 Error Codes and the Corresponding Corrective Actions
Error Code
10001
10004
10009
10010
10413
10500
10501
10502
10504
Error Message
Your payment can't be processed right now. Please try again later.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your credit card has expired.
Please pay with a valid card.
Please enter a valid card security code.
Corrective Action
Try again later.
There is a problem with your integration. Check the parameters that you have supplied.
Try again later.
Provide a valid invoice ID.
Subtotal, shipping, handling, and tax. Review the totals in your integration.
You have not agreed to the billing agreement.
Billing agreement is disabled or inactive.
Credit card used has expired.
CVV provided is invalid. The CVV is between 3-4 digits long.
85
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10507
10508
10509
10511
10512
10513
10520
10523
10525
10527
10534
10535
10536
Error Message
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a valid card expiration date.
Corrective Action
Your PayPal account is restricted. Contact PayPal with this error code.
Expiration date must be in the correct format.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a first name.
Please enter a last name.
PayPal was unable to determine the IP address of the buyer.
Review the integration to ensure that a valid
PaymentAction value is supplied.
First name of the buyer is required.
Last name of the buyer is required.
Amounts supplied do not match.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed right now. Please try again later.
Try again later.
Please enter a valid amount. Verify your integration to ensure that the amounts are not zero.
Please enter a valid card number.
Credit card entered is invalid.
Credit card entered is currently restricted by PayPal.
Contact PayPal with this error code.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a valid credit card number.
Credit card entered is invalid.
Your payment can't be processed. Please contact the merchant directly with this code.
All shopping cart items must be in the same currency.
86
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10539
10540
10541
10542
10544
10545
10546
10547
10548
10549
10550
Error Message Corrective Action
Your payment can't be processed. Please contact the merchant directly with this code.
Transaction was declined by fraud filter managed by the merchant. To accept this translation, change your risk settings on PayPal.
Please enter a valid address.
Transaction was declined by PayPal because of an invalid address. Buyer should provide the correct address.
Please enter a valid credit card number.
Please enter a valid email address.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can’t be processed. Please pay with another credit card.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Credit card entered is currently restricted by PayPal.
Contact PayPal with this error code.
Email address is in an invalid format. Buyer should provide the email address in the correct format.
Transaction was declined by PayPal. Contact PayPal with this error code.
Transaction was declined by PayPal because of possible fraudulent activity. Contact PayPal with this error code.
Transaction was declined by PayPal because of possible fraudulent activity on the IP address. Contact PayPal with this error code.
None - this is a PayPal internal error.
Merchant account attempting the transaction is not a business account at PayPal. Check your account settings.
Merchant account attempting the transaction is not able to process Direct Payment transactions. Contact PayPal with this error code.
Access to Direct Payment was disabled for your account. Contact PayPal with this error code.
87
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10552
10553
10557
10558
10561
10562
10563
10564
10565
10566
10570
10701
Error Message
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a complete billing address.
Please enter a valid year for the credit card expiration date.
Please enter a valid month for the credit card expiration date.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please pay with a different card type.
Your payment can’t be processed. Please pay with another credit card.
Please enter a valid name for the billing address.
Corrective Action
Merchant account attempting the transaction does not have a confirmed email address with PayPal. Check your account settings.
Merchant attempted a transaction where the amount exceeded the upper limit for that merchant.
Check your payment receiving preferences. Contact
PayPal if you more help.
Credit card supplied cannot be charged in the currency requested.
Buyer should enter the complete billing address.
Buyer should enter a valid year for card expiration.
Buyer should enter a valid month for card expiration.
A duplicate transaction was detected, advice buyer to try again later.
Merchant country is not supported.
Credit card type is not supported.
Credit card supplied doesn’t support “Authorization”.
Buyer should enter a valid name in the billing address.
88
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
10712
10713
10714
10715
10716
10717
10718
Error Message
Please enter a valid address in line 1 of the billing address.
Please enter a valid address in line 2 of the billing address.
Please enter a valid city in the billing address.
Please enter a valid state in the billing address.
Please enter a valid ZIP code in the billing address.
Please enter a valid country in the billing address.
Please enter a complete billing address.
Please enter an address in line 1 of the billing address.
Please enter a city in the billing address.
Please enter a state in the billing address.
Please enter a valid postal code in the billing address.
Please enter a country in the billing address.
Please enter a valid name in the billing address.
Please enter a valid state in the billing address.
Please enter a valid postal code in the billing address.
Please enter a valid postal code in the billing address.
Please enter a valid city in the billing address.
Corrective Action
Buyer should enter a valid address in line 1 of the billing address.
Buyer should enter a valid address in line 2 of the billing address.
Buyer should enter a valid city in the billing address.
Buyer should enter a valid state in the billing address.
Buyer should enter a valid zip code in the billing address.
Buyer should enter a valid country in the billing address.
Buyer should enter the complete billing address.
Buyer should enter an address in line 1 of the billing address.
Buyer should enter a city in the billing address.
Buyer should enter a state in the billing address.
Buyer should enter a valid zip code in the billing address.
Buyer should enter a country in the billing address.
Buyer should enter a valid name in the billing address.
Buyer should enter a valid state in the billing address.
Buyer should enter a valid zip code in the billing address.
Buyer should enter a valid zip code in the billing address.
Buyer should enter a valid city.
89
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10719
10720
10721
10722
10723
10724
Error Message
Please enter a valid addressee name in the shipping address.
Please enter a valid address in line 1 of the shipping address.
Please enter a valid address in line 2 of the shipping address.
Please enter a valid city in the shipping address.
Please enter a valid state in the shipping address.
Please enter a valid postal code in the shipping address.
Corrective Action
Buyer should enter a valid addressee name for shipping address.
Buyer should enter a valid address in line 1 of the shipping address.
Buyer should enter a valid address in line 2 of the shipping address.
Buyer should enter a valid city in the shipping address.
Buyer should enter a valid state in the shipping address.
10725
10726
Please enter a valid country in the shipping address.
Buyer should enter a valid postal code in the shipping address.
Buyer should enter a valid country in the shipping address.
Buyer should enter a complete shipping address.
10727
10728
10729
10730
10731
10732
10733
10734
Please enter a complete shipping address.
Please enter an address in line 1 of the shipping address.
Please enter a city in the shipping address.
Please enter a state in the shipping address.
Please enter a postal code in the shipping address.
Please enter a country in the shipping address.
Please enter a valid addressee name in the shipping address.
Please enter a valid state in the shipping address.
Please enter a valid postal code in the shipping address.
Buyer should enter an address1 in the shipping address.
Buyer should enter a city in the shipping address.
Buyer should enter a state in the shipping address.
Buyer should enter a valid postal code in the shipping address.
Buyer should enter a country in the shipping address.
Buyer should enter a valid addressee in the shipping address.
Buyer should enter a valid state in the shipping address.
Buyer should enter a valid postal code in the shipping address.
90
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10735
10736
10744
10745
10746
10747
10748
10750
10751
10752
10754
10755
10756
10759
Error Message
Please enter a valid postal code in the shipping address.
Please enter a valid city and state in the shipping address.
Please enter a valid country in the billing address.
Please enter a valid country in the shipping address.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a card security code.
Please enter a valid state in the shipping address.
Please enter a valid state in the billing address.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please pay with another card.
Corrective Action
Buyer should enter a valid postal code in the shipping address.
Buyer should enter a valid city and state in the shipping address.
Buyer should enter a valid country in the billing address.
Buyer should enter a valid country in the shipping address.
Credit card from this country is not supported.
Contact PayPal with this error code.
Buyer should enter a Card Security Code.
Buyer should enter a valid state in the shipping address.
Buyer should enter a valid state in the billing address.
Transaction was declined by the issuing bank, not
PayPal. Buyer should attempt another card.
Buyer should use a different credit card.
Review your integration to ensure that the currency code is supported.
Buyer should use a different credit card.
Transaction was declined by PayPal. Contact PayPal with this error code.
91
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
10761
10762
10763
10764
11998
15001
15002
15003
15004
15005
15006
15007
Error Message
Your payment can't be processed because this transaction appears to be a duplicate of a recent transaction.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter the date when your credit card became valid.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please pay with another card.
Your payment can't be processed. Please contact the merchant directly with this code.
Please enter a valid Card
Security Code.
Your payment can't be processed. Please pay with another card.
Please enter a valid card number.
Your card is expired. Please pay with a valid card.
Corrective Action
Transaction was declined because PayPal is currently processing a transaction by the same buyer for the same amount. This error can occur when a buyer submits multiple, identical transactions in quick succession.
Excessive CVV failures on the credit card. Buyer should try a different card.
None - this is a PayPal internal error.
Transaction was declined by PayPal. Contact PayPal with this error code.
Buyer should give the correct start date for their credit card.
Transaction was rejected by PayPal because of excessive failures over a short period of time for this credit card. Contact PayPal with this error code.
Transaction was declined by PayPal. Contact PayPal with this error code.
Transaction was declined because the merchant does not have a valid commercial entity agreement on file with PayPal. Contact PayPal with this error code.
Transaction was declined because the CVV entered does not match the credit card.
Transaction was declined by the issuing bank, not
PayPal. Buyer should attempt another card.
Transaction was declined by the issuing bank, not
PayPal. Buyer should attempt another card.
Transaction was declined by the issuing bank because of an expired credit card. Buyer should attempt another card.
92
Error Messages
T ABLE C.1 Error Codes and the Corresponding Corrective Actions (Continued)
Error Code
15008
15009
99998
Error Message
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Your payment can't be processed. Please contact the merchant directly with this code.
Corrective Action
Review your integration to ensure that the totals match.
There is a mismatch in the currency code. Contact
PayPal with this error code.
Credit card data is invalid. Contact PayPal with this error code.
93
Error Messages
94
D
Currency Codes
The table below lists all the currencies supported by PayPal.
T ABLE D.1 Currency Codes
NOK
NZD
PLN
SEK
GBP
HKD
HUF
JPY
SGD
USD
Currency
Code
AUD
CAD
CHF
CZK
DKK
EUR
Country Name
Australian Dollar
Canadian Dollar
Swiss Franc
Czech Koruna
Danish Krone
Euro
British Pound Sterling
Hong Kong Dollar
Hungarian Forint
Japanese Yen
Norwegian Krone
New Zealand Dollar
Polish Zloty
Swedish Krona
Singapore Dollar
U.S. Dollar
96
Currency Codes
Index
A
address_override 17 address1 17 address2 17
B
BMCreateButton API Operation 45
BMCreateButton Request Fields 45
BMCreateButton Response Fields 46
button hosting 39 clear text buttons 39 encrypted buttons 39 token buttons 39
C
cancel_return 18 cbt 18 city 18
D
E
ENCRYPTED 39 encrypted buttons 39
F
G
GetTransactionDetails API 56, 63
97
98
Index
H
headerBgColor 31 headerHeight 31
I
Instant Payment Notification (IPN) 55
integration
L
logoFont 31 logoFontColor 31 logoFontSize 31 logoImage 31 logoImagePosition 31 logoText 31
M
N
night_phone_a 18 night_phone_b 18 night_phone_c 18 notify_url 18
O
orderSummaryBgColor 31 orderSummaryBgImage 31
P
pageButtonBgColor 31 pageButtonTextColor 31 pageTitleTextColor 31
preview 26 previous version 26
public certificate
R
S
showBillingAddress 32 showBillingEmail 32 showBillingPhone 32
showCustomerName 32 showHostedThankyouPage 32 showShippingAddress 32
T
W
Z
Index
99
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
PCI Compliance assistance
Hosted payment page for security
Supports major credit/debit cards & PayPal
Seller Protection program
Customizable payment page
HTML and API integration options
iFrame integration for seamless checkout
Sandbox environment for testing
Frequently asked questions
By using PayPal's hosted payment page, you avoid storing sensitive credit card data on your website, which helps meet PCI DSS requirements. Note that implementation doesn't guarantee full compliance.
It protects you against chargebacks on transactions made through PayPal Pro, covering items sold domestically and internationally using credit cards or PayPal accounts. Conditions apply.
You can customize it by modifying settings in your PayPal profile or by adding HTML variables to the payment page's code. HTML variables override profile settings.
You can integrate using HTML forms or the PayPal API. iFrame integration is also provided for embedding the payment form directly on your site.
Use PayPal's Sandbox environment to test your integration and settings before going live.