PayPal Payments Advanced: Getting Started with Hosted Pages
This guide contains the following sections:
PayPal Payments Advanced (PPA) enables merchants to accept PayPal and credit cards. PPA provides merchants with a PayPal merchant account. Integration with PPA is similar to integration with the PayPal Payflow Gateway.
This document shows how to get a secure token from the Payflow pilot endpoint and then submit the token in a test call. For a more comprehensive document that shows you how to set up, customize, and test hosted pages, see Set up and test hosted pages. For the benefits and requirements of PPA, and links to other documentation, see the PPA product page.
PayPal's hosted checkout pages (also called hosted checkout templates) enable you to pass transaction data securely to the server and collect credit card information. Although the Make your first call section, below, describes an initial customization of hosted pages, please refer to the Payflow Gateway Developer Guide and Reference after your initial test calls.
PPA requires use of PayPal's hosted checkout templates for submitting data for sales and authorizations. The templates enable merchants to avoid the PCI burden of having credit card details pass through their servers.
The secure token, utilized as part of a PPA integration, helps protect transaction data. You must use a secure token with hosted checkout pages. The token is good for one transaction and is valid for 30 minutes. The token and its token ID are used by the server to retrieve and display the transaction data for customer approval.
Make your first call
Before making an initial call to the Payflow pilot endpoint (https://pilot-payflowpro.paypal.com), sign up for a PayPal Payments Advanced (PPA) account at http://www.paypal.com/advanced. Also see the steps below for adding a user to the account, to utilize for API calls. A merchant should create a user account for transactions. Otherwise, if the password for merchant login ID changes, API calls fail.
Therefore, after you have signed up for your PPA account at http://www.paypal.com/advanced, add a user to the account:
- Using the merchant login and password of the PayPal Payments Advanced account, log in to PayPal Manager.
- Click Account Administration.
- Under Manage Users, click Add User.
- Fill in the fields under Admin Configuration, User Information, and User Login Information.
- Under Assign Privilege to User, in the Select a Predefined Role field, you can select FULL_TRANSACTIONS. Leave User Status as Active.
- Click the Update button.
For more information about the fields, click the Help button.
Set up hosted checkout pages
Using the PayPal Payments Advanced account that you obtained above, log in to PayPal Manager.
In the Service Summary section of the page, under Service, click Hosted Checkout Pages.
On the landing page titled Hosted Checkout Pages, click Set Up.
Initially, for test purposes, we'll leave most fields on this Set Up page blank. When you later fill out more Set Up page fields, be sure to click the Help button on this same page for extensive information. Also see the Payflow Gateway Developer Guide and Reference.
On this Set Up page, enter the following values. (Other values on the Set Up page are unnecessary for your initial test call.)
- PayPal Sandbox email address. The email you used for your PayPal sandbox account, which is part of your profile at https://developer.paypal.com.
- Return URL. In the Payment Confirmation section of the page, enter a return URL (for use if the consumer proceeds with payment). For the return URL method, specify POST.
- Enable Secure Token. Set to Yes.
On this Set Up page, click Save Changes.
Click Customize, choose Layout C, and click Save and Publish.
Get a secure token from the pilot URL
As described in the Payflow Gateway Developer Guide and Reference, you can send test data, e.g. as name-value pairs, to the Payflow pilot endpoint (https://pilot-payflowpro.paypal.com).
The following table contains parameters for a test call to obtain a secure token:
|PARTNER||The Payflow partner. The example below uses PayPal since PayPal Payments Advanced includes a PayPal merchant account.|
|VENDOR||The Merchant Login ID that you use to log into PayPal Manager.|
|USER||The name of the user whom you added to your account using PayPal Manager, above.|
|PWD||The password of the user whom you added to your account using PayPal Manager, above.|
|TRXTYPE||The type of the transaction, e.g.
|AMT||The amount of the sale.|
|CREATESECURETOKEN||Specify a value of
|SECURETOKENID||An ID that you create for the token that will be returned from the Payflow pilot endpoint (https://pilot-payflowpro.paypal.com). Use a unique alphanumeric value, up to 36 characters long. For example, you could specify
For demonstration purposes, the following example uses cURL to obtain a secure token that you will use in a subsequent test call.
See the parameter descriptions in the table above for the values to substitute in the following example for
curl https://pilot-payflowpro.paypal.com \ -s \ --insecure \ -d PARTNER=PayPal \ -d VENDOR=MyMerchantID \ -d USER=UserID \ -d PWD=UserPassword \ -d TRXTYPE=S \ -d AMT=40 \ -d CREATESECURETOKEN=Y \ -d SECURETOKENID=12528208de1413abc3d60c86cb15
The response should be similar to the following. The response contains
RESULT=0 for success, a
SECURETOKEN (for use in a subsequent transaction call), a
SECURETOKENID (which you provided in the request to identify the received token), and a
RESPMSG value of
RESULT=0& SECURETOKEN=123456NYslUGMy0tlKafELwct& SECURETOKENID=12528208de1413abc3d60c86cb15& RESPMSG=Approved
Using the Secure Token and Obtaining Transaction Details
The secure token (obtained above) can be used in an
iframe tag from within a test HTML file. The
iframe tag enables you to embed the PayPal hosted page that you customized above.
Note: In contrast to the test code below (in which only the
iframewindow redirects after payment), the parent window generally should redirect. Therefore, in contrast to the test code below, you can create an intermediary page, to which PayPal will redirect, and using that intermediary page, capture the return data and force the customer's browser to redirect to your final receipt page.
In the test code below, the following parameters are used in the
iframe tag, which points to the Payflow Link endpoint (https://payflowlink.paypal.com). After using the test HTML file below, you can begin adding parameters and functionality specific to your PPA integration; see the Payflow Gateway Developer Guide and Reference.
The following test HTML file submits the secure token in test mode. This table contains the parameters for the
iframe tag in the HTML file:
|SECURETOKENID||Specify the ID that you created (described above) for the secure token. When you submit the secure token (below), use the same
|SECURETOKEN||Specify the value of the
Create the test HTML file below. Then, in the
src attribute of the
iframe tag, substitute your own
SECURETOKEN values. This test HTML file illustrates how to include a hosted page in a merchant page, to enable the merchant to accept payments.
<html> <head> <title></title> </head> <body> <p>This is a test HTML file.</p> <iframe src="https://payflowlink.paypal.com?MODE=TEST&SECURETOKENID=MySecureTokenID&SECURETOKEN=MySecureToken" name="test_iframe" scrolling="no" width="570px" height="540px"></iframe> </body> </html>
Save and open the above HTML file in a browser. Below the text that says, "this is a merchant page," the
iframe (inline-frame) part of the page is displayed. This "hosted checkout" part of the page enables a customer to choose to pay with PayPal or with a credit card, and then make the payment.
Receive the transaction data
iframe part of the page above, in which the hosted checkout frame is displayed, enter a test credit card number of 4111111111111111 and expiration date values of 12 and 12. Then click Pay Now. The following confirmation page is displayed:
This confirmation page enables the customer to click "Return to the merchant's website." If you click that link, the following occurs: The server redirects your browser to your return URL, i.e. the return URL that you provided on the Set Up page in PayPal Manager. (See "Setting up Hosted Checkout Pages," above. Note that the Help button on the Set Up page, in PayPal Manager, contains information about customization options.)
In redirecting your browser to the return URL, the server sends transaction data to the return URL, via POST.
In our example, the transaction data, returned via POST, would be the following, without link breaks:
TYPE=S& RESPMSG=Approved& ACCT=1234& COUNTRY=US& VISACARDLEVEL=12& TAX=0.00& CARDTYPE=0& PNREF=12341EE308F6& TENDER=CC& AVSDATA=XXN& METHOD=CC& SECURETOKEN=123456NYslUGMy0tlKafELwct& SHIPTOCOUNTRY=US& AMT=40.00& SECURETOKENID=12528208de1413abc3d60c86cb15& TRANSTIME=2012-03-26+14%3A07%3A59& HOSTCODE=A& COUNTRYTOSHIP=US& RESULT=0& AUTHCODE=124PNI& EXPDATE=1212
You can parse this transaction data as necessary. See the Payflow Gateway Developer Guide and Reference for informaton about other parameters that can be sent to your return URL via POST.