PayPal Payments Pro Integration Guide Last updated: April 2012
PayPal Payments Pro Integration Guide Document Number: 100001.en_US-201204 © 2010-2011 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Checkout Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Payment Option Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Express Checkout Building Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 PayPal Button and Logo Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Express Checkout API Operations . . . .
Contents Redirecting the Buyer to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Getting Buyer Details Using GetExpressCheckoutDetails . . . . . . . . . . . . . . . . 65 Creating the Profiles With CreateRecurringPaymentsProfile . . . . . . . . . . . . . . 65 Options for Creating a Recurring Payments Profile . . . . . . . . . . . . . . . . . . . . . 66 Specifying the Regular Payment Period . . . . . . . . . . . . . . . . . . . . . . . . . 66 Including an Optional Trial Period . . . . .
Contents URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Appendix B Implementing 3-D Secure Transactions (UK Only) . . . . . 87 Introduction to 3-D Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Integration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Cardinal Commerce Registration and Installation . . . . . . . . . . . . . . . . . . . . . . 88 Transaction Processing . . . . . . . . . . . .
Preface This document describes PayPal Payments Pro (known as Website Payments Pro outside the U.S.) integration. Intended Audience This document is intended for merchants and developers implementing PayPal Payments Pro. Revision History Revision history for PayPal Payments Pro Integration Guide. Date Description 04/03/12 Updated references to Website Payments Standard and Website Payments Pro to PayPal Payments Standard and PayPal Payments Pro, respectively.
Where to Go for More Information Date Description 06/04/09 Added a chapter on pre-populating the PayPal review page. Updated PayPal Review pages. Moved some customization topics out of this guide. They are now in the Merchant Setup and Administration Guide. 04/08/09 Added a chapter describing the Instant Update Callback API. Added Express Checkout feature of passing AMT=0 to create one or more billing agreements. 12/11/08 Revised the Website Payments Pro introduction and overview chapters.
1 Introducing PayPal Payments Pro You can accept credit and debit cards and PayPal payments directly on your website using 2 API-based solutions: Direct Payment and Express Checkout. You must integrate with both Direct Payment and Express Checkout to use PayPal Payments Pro, known as Website Payments Pro outside the U.S.
1 Introducing PayPal Payments Pro Additional Features of PayPal Payments Pro From your shopping cart, a buyer can either checkout with Express Checkout, starting from the Checkout with PayPal button on your Shopping Cart page, or pay directly by credit or debit card using Direct Payment. If a buyer pays using Express Checkout, PayPal provides a checkout experience that streamlines checkout. Even if buyers do not pay using Express Checkout, they can still pay by credit or debit card using Direct Payment.
Introducing PayPal Payments Pro Additional Features of PayPal Payments Pro 1 Settlements and Captured Payments Often, you accept a payment and ship goods immediately, which is refered to as sale. In addition to immediate payments, Direct Payment and Express Checkout both allow you to authorize payments to be captured later, which is referred to as an authorization.
1 Introducing PayPal Payments Pro Additional Features of PayPal Payments Pro phone, fax, or by mail and want to accept credit cards. An optional card reader is available to process face-to-face purchases; however, some restrictions apply. You can use Virtual Terminal on any computer with an internet connection and a web browser. For more information about Virtual Terminal, see Virtual Terminal Users Guide.
Introducing PayPal Payments Pro PayPal Payments Pro API Operations eCheck payments and associated status, such as pending, completed, or denied, and payments pending for other reasons, such as those being reviewed for potential fraud Recurring payment and subscription actions Chargebacks, disputes, reversals, and refunds associated with a transaction 1 For more information about IPN, see Instant Payment Notification Guide PayPal Payments Pro API Operations The PayPal API supports a range of f
1 Introducing PayPal Payments Pro PayPal Payments Pro API Operations PayPal API Operation Description DoReauthorization Reauthorize a previously authorized payment. DoVoid Void an order or an authorization. Recurring Payment API operations: CreateRecurringPaymentsProfile Create a recurring payments profile. GetRecurringPaymentsProfileDetails Obtain information about a recurring payments profile. ManageRecurringPaymentsProfileStatus Cancel, suspend, or reactivate a recurring payments profile.
Introducing PayPal Payments Pro Website Payments Pro Regional Differences 1 Website Payments Pro Regional Differences Website Payments Pro is available in the United States, Canada, and the United Kingdom. Minor regional differences include transaction limits, the kinds of credit cards accepted, and address information.
1 Introducing PayPal Payments Pro Website Payments Pro Regional Differences Credit Card Currencies by Country The following currencies are supported for Direct Payment: Currencies and Currency Codes Supported by Express Checkout and Direct Payment Express Checkout Currency Currency Code Direct Payment Currency for Specified Card in United States Direct Payment Currency for Specified Card in United Kingdom Direct Payment Currency for Specified Card in Canada Australian Dollar AUD Visa, MasterCard V
Introducing PayPal Payments Pro Website Payments Pro Regional Differences 1 Addresses For Canada, specify the province abbreviation in the State field. For Great Britain, the State field is ignored; however, you still may need to specify a value in the State field; for example you can specify the city for both the city and state. For more information about addresses, see the PayPal Developer Network.
1 18 Introducing PayPal Payments Pro Website Payments Pro Regional Differences April 2012 PayPal Payments Pro Integration Guide
2 Introducing Direct Payment Direct Payment lets buyers who do not have a PayPal account use their credit cards without leaving your website. PayPal processes the payment in the background. The Direct Payment User Experience User Interface Recommendations for Direct Payment Checkout The Direct Payment User Experience Direct Payment enables buyers to pay by credit or debit card during your checkout flow. You have complete control over the experience; however, you must consider PCI compliance.
2 Introducing Direct Payment The Direct Payment User Experience – Credit card CSC value – Cardholder first and last name – Cardholder billing address The following example shows the collection of credit card information from a US buyer after the transaction amount has been determined: NOT E : In some cases, the billing address and CSC value may be optional. You must also identify debit on your PCI compliant checkout page when you reference a direct card checkout image. 2.
Introducing Direct Payment User Interface Recommendations for Direct Payment Checkout – – – – – 2 AVS response code CSC response code PayPal transaction ID Error codes and messages (if any) Correlation ID (unique identifier for the API call) 5. If the operation is successful, you send the buyer to an order confirmation page. The Ack code determines whether the operation is a success. – If successful, you should display a message on the order confirmation page.
2 22 Introducing Direct Payment User Interface Recommendations for Direct Payment Checkout April 2012 PayPal Payments Pro Integration Guide
3 Introducing Express Checkout Express Checkout is PayPal’s premier checkout solution that streamlines the checkout process for buyers and keeps them on a merchant’s website after making a purchase. The Express Checkout Experience Express Checkout Integration Steps Express Checkout Flow Express Checkout Building Blocks The Express Checkout Experience Express Checkout makes it easier for buyers to pay online.
3 Introducing Express Checkout Express Checkout Integration Steps Express Checkout flow In the Express Checkout flow, the buyer: 1. Chooses Express Checkout by clicking Check out with PayPal 2. Logs into PayPal to authenticate his or her identity 3. Reviews the transaction on PayPal NOT E : Optionally, (not shown in the diagram), the buyer can then proceed to review the order on your site. You can also include other checkout steps, including upselling on your Confirm order page. 4.
Introducing Express Checkout Express Checkout Integration Steps 3 Configuring and Customizing the Express Checkout Experience After you implement and test your basic Express Checkout integration, you should configure the additional features of Express Checkout to customize it to meet your needs. Carefully evaluate each feature because the more you streamline the checkout process and make Express Checkout seamless to buyers, the more likely your sales will increase.
3 Introducing Express Checkout Express Checkout Flow Express Checkout Flow To implement Express Checkout, you must offer it both as a checkout option and as a payment method. Typically, you initiate the Express Checkout flow on your shopping cart page and on your payment options page. You add Express Checkout to your existing flow by placing the Checkout with PayPal button on your Shopping Cart page and by placing the PayPal mark on your Payment Methods page.
Introducing Express Checkout Express Checkout Building Blocks 3 Payment Option Entry Point The payment option entry point is one of the places where you must implement Express Checkout. Buyers initiate the Express Checkout flow on your payment methods page by selecting PayPal as the default option.
3 Introducing Express Checkout Express Checkout Building Blocks A token is a value assigned by PayPal that associates the execution of API operations and commands with a specific instance of a user experience flow. NOT E : Tokens are not shown in the diagram. PayPal Button and Logo Images To inform buyers that PayPal is accepted on your website, you must place PayPal button and logo images in your checkout flow. PayPal recommends that you use dynamic images.
Introducing Express Checkout Express Checkout Building Blocks 3 Express Checkout Images The Check out with PayPal button is the image you place on your shopping cart page. The US version of the image looks like this. To create an Express Checkout button, see https://www.paypal.com/us/cgibin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal also provides buttons for other countries.
3 Introducing Express Checkout Express Checkout Building Blocks To create a PayPal mark, see https://www.paypal.com/cgibin/webscr?cmd=xpt/Marketing/general/OnlineLogoCenter-outside. Express Checkout API Operations The PayPal API provides three API operations for Express Checkout. These API operations set up the transaction, obtain information about the buyer, and handle the payment and completes the transaction. API Operation Description SetExpressCheckout Sets up the Express Checkout transaction.
Introducing Express Checkout Express Checkout Building Blocks 3 Express Checkout Token Usage Express Checkout uses a token to control access to PayPal and execute Express Checkout API operations. The SetExpressCheckout API operation returns a token, which is used by other Express Checkout API operations and by the _ExpressCheckout command to identify the transaction. The life of the token is approximately 3 hours.
3 32 Introducing Express Checkout Express Checkout Building Blocks April 2012 PayPal Payments Pro Integration Guide
4 Getting Started With Direct Payment To get started with Direct Payment, implement and test the simplest DoDirectPayment API operation, which is a sale. Then you can expand your use of Direct Payment to include authorization and capture.
4 Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL 4. Specify information about the credit or debit card.
Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL 4 The following steps show how you can test the DoDirectPayment API operation: 1. Execute the DoDirectPayment API operation to complete the transaction. The following example uses cURL to communicate with PayPal: curl --insecure ^ https://api-3t.sandbox.paypal.com/nvp ^ -d "VERSION=56.0^ &SIGNATURE=api_signature^ &USER=api_username^ &PWD=api_password^ &METHOD=DoDirectPayment^ &PAYMENTACTION=Sale^ &IPADDRESS=192.168.0.1^ &AMT=8.
4 36 Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL April 2012 PayPal Payments Pro Integration Guide
Getting Started With Direct Payment Testing Direct Payment Using NVP and cURL 4 4. Click the Details link to see the status of the transaction.
4 Getting Started With Direct Payment Direct Payment Authorization and Captures Direct Payment Authorization and Captures You can use PayPal API operations to handle the capture of payments authorized using DoDirectPayment.
Getting Started With Direct Payment Direct Payment Authorization and Captures 4 Captures attempted outside of the honor period result in PayPal contacting the card issuer to reauthorize the payment; however, the reauthorization and, thus, the capture might be declined. If you know that you will capture after the honor period expires, PayPal recommends that you call DoReauthorization to explicitly reauthorize the honor period before attempting to capture the payment.
4 Getting Started With Direct Payment Direct Payment Authorization and Captures IM PORT AN T : Never use post actions for live transactions; they are not secure. In your DoDirectPayment request, set the payment action to Authorization:
Getting Started With Direct Payment Direct Payment Authorization and Captures 4
4 Getting Started With Direct Payment Direct Payment Authorization and Captures
Getting Started With Direct Payment Direct Payment Authorization and Captures 4 AUTHORIZATIONID=6HB59926VL998415S&TIMESTAMP=2010%2d03%2d08T20%3a37%3a48Z&CO RRELATIONID=797da6e380c0&ACK=Success&VERSION=62%2e0&BUILD=1218643&PAYMENTST ATUS=Pending&PENDINGREASON=authorization&PROTECTIONELIGIBILITY=Ineligible Use the new authorization ID in the DoCapture request:
4 44 Getting Started With Direct Payment Direct Payment Authorization and Captures April 2012 PayPal Payments Pro Integration Guide
5 Getting Started With Express Checkout To implement Express Checkout, start with the simplest Express Checkout integration and test it. Then you can decide the kind of payment settlement actions you want to support.
5 Getting Started With Express Checkout Implementing the Simplest Express Checkout Integration METHOD=SetExpressCheckout VERSION=XX.0 2. Specify your API credentials. Use the following parameters for a signature: USER=API_username PWD=API_password SIGNATURE=API_signature In the Sandbox, you can always use the following signature: USER=sdk-three_api1.sdk.com PWD=QFZCWN5HZM8VBG7Q SIGNATURE=A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU 3.
Getting Started With Express Checkout Implementing the Simplest Express Checkout Integration NOT E : 5 You can pass SetExpressCheckout request values as parameters in your URL to have the values available, if necessary, after PayPal redirects to your URL. CANCELURL=cancel_url 6. Specify the payment action.
5 Getting Started With Express Checkout Implementing the Simplest Express Checkout Integration 2. Specify your API credentials. Use the following parameters for a signature: USER=API_username PWD=API_password SIGNATURE=API_signature 3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site. PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API. TOKEN=tokenValue 4.
Getting Started With Express Checkout Testing an Express Checkout Integration 5 2. Specify your API credentials. Use the following parameters for a signature: USER=API_username PWD=API_password SIGNATURE=API_signature 3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site. PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API. TOKEN=tokenValue 4.
5 Getting Started With Express Checkout Testing an Express Checkout Integration The following diagram shows the Express Checkout execution flow, which uses the Sandbox as the API server. The pages on the left represent your site. The following steps match the circled numbers in the diagram. Perform the actions in each step to test Express Checkout. 1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox.
Getting Started With Express Checkout Testing an Express Checkout Integration 5
5 Getting Started With Express Checkout Testing an Express Checkout Integration http://www.YourReturnURL.com/ ?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8 5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox:
Getting Started With Express Checkout Handling Payment Settlements With Express Checkout 5
5 Getting Started With Express Checkout Handling Payment Settlements With Express Checkout Sale Payment Action for Express Checkout A sale payment action represents a single payment that completes a purchase for a specified amount. A sale is the default Express Checkout payment action; however, you can also specify the following action in your SetExpressCheckout and DoExpressCheckoutPayment requests: PAYMENTREQUEST_n_PAYMENTACTION=Sale A sale is the most straightforward payment action.
Getting Started With Express Checkout Handling Payment Settlements With Express Checkout 5 API operations associated with Authorization payment action in Express Checkout API Operation Description DoCapture Capture an authorized payment. DoReauthorization Reauthorize a payment. DoVoid Void an order or an authorization. Order Payment Action for Express Checkout An order payment action represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days.
5 Getting Started With Express Checkout Issuing Refunds API operations associated with Order payment action in Express Checkout API Operation Description DoAuthorization Authorize a payment. DoCapture Capture an authorized payment. DoVoid Void an order or an authorization. Issuing Refunds You can use the RefundTransaction PayPal API operation to issue refunds.
Getting Started With Express Checkout Issuing Refunds 5 AMT=amount CURRENCYCODE=currencyID 4. For a partial refund, specify the memo description. NOTE=description 5. Execute the RefundTransaction operation. 6. Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful.
5 58 Getting Started With Express Checkout Issuing Refunds April 2012 PayPal Payments Pro Integration Guide
6 Integrating Recurring Payments Both Direct Payment and Express Checkout support recurring payments. You can set up a recurring payment to handle a subscription and other payments that occur on a fixed schedule.
6 Integrating Recurring Payments Recurring Payments Terms Get information details about a recurring payments profile. Change the status of a recurring payments profile. Update the details of the recurring payments profile. Bill the outstanding amount of the recurring payments profile. Limitations The current release of the Recurring Payments API has the following limitations: A profile can have at most one optional trial period and a single regular payment period.
Integrating Recurring Payments Recurring Payments With Direct Payment Term Definition Trial period An optional subscription period before the regular payment period begins. A trial period may not have the same billing cycles and payment amounts as the regular payment period. Payment amount The amount the buyer pays for each billing cycle. Outstanding balance If a payment fails for any reason, PayPal adds that amount to the profile’s outstanding balance.
6 Integrating Recurring Payments Recurring Payments With the Express Checkout API The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile. For more options when creating a recurring payments profile, see “Options for Creating a Recurring Payments Profile” on page 66. As with all direct payments, PayPal is completely invisible to your buyer before, during, and after the purchase.
Integrating Recurring Payments Recurring Payments With the Express Checkout API 6 The circled numbers in the diagram correspond to the numbered steps in the following table: Recurring payments processing flow Step Merchant... PayPal... 1 Calls SetExpressCheckout, setting up one or more billing agreements in the request. 2 3 Returns a token, which identifies the transaction, to the merchant. Redirects buyer’s browser to: https://www.paypal.
6 Integrating Recurring Payments Recurring Payments With the Express Checkout API Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one-time purchase or recurring payment NOT E : You can also initiate the processing flow using SetCustomerBillingAgreement for orders that contain only a single recurring payment. Typically, you set the amount of the payment for an Express Checkout transaction when you call the SetExpressCheckout request.
Integrating Recurring Payments Recurring Payments With the Express Checkout API 6 When redirecting the buyer to PayPal, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL as the value of the Location header in the HTTPS response. Make sure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.
6 Integrating Recurring Payments Options for Creating a Recurring Payments Profile NOT E : The payment details item fields are available with version 69.0 and later of the CreateRecurringPaymentsProfile API. The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile. The following is a CreateRecurringPaymentsProfile example that enables you to obtain the best rates for digital goods items.
Integrating Recurring Payments Options for Creating a Recurring Payments Profile 6 Required fields for specifying a regular payment period NVP SOAP Description PROFILESTARTDATE RecurringPaymentsProfileDet ails.BillingStartDate The date when billing for this profile begins. NOT E : The profile may take up to 24 hours for activation. BILLINGPERIOD ScheduleDetails. PaymentPeriod.BillingPeriod The unit of measure for the billing cycle.
6 Integrating Recurring Payments Options for Creating a Recurring Payments Profile Required fields for specifying a trial period NVP SOAP TRIALBILLINGPERIOD ScheduleDetails.TrialPeriod.BillingPeriod TRIALBILLINGFREQUENCY ScheduleDetails.TrialPeriod.BillingFrequency TRIALAMT ScheduleDetails.TrialPeriod.Amount TRIALTOTALBILLINGCYCLES ScheduleDetails.TrialPeriod.
Integrating Recurring Payments Recurring Payments Profile Status 6 Billing the Outstanding Amount If a payment fails for any reason, PayPal adds the billing amount (including shipping and tax, if applicable) to the profile’s outstanding balance. Use the AUTOBILLOUTAMT field in the CreateRecurringPaymentsProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle.
6 Integrating Recurring Payments Getting Recurring Payments Profile Information CancelOnFailure in the CreateRecurringPaymentsProfile request, PayPal creates the profile with a status of PendingProfile. The profile remains in this status until the initial payment either completes successfully or fails. A profile has a status of ExpiredProfile when PayPal completes the total billing cycles for the optional trial and the regular payment periods.
Integrating Recurring Payments Modifying a Recurring Payments Profile 6 You can modify only the following specific information about an active or suspended profile: Subscriber name or address Past due or outstanding amount Whether to bill the outstanding amount with the next billing cycle Maximum number of failed payments allowed Profile description and reference Number of additional billing cycles Billing amount, tax amount, or shipping amount NOT E : You cannot modify the bi
6 Integrating Recurring Payments Billing the Outstanding Amount of a Profile If, for example, you create a profile on March 10 with a total amount of $100, during the 180day interval from March 10 to September 6, you can increase the amount to a maximum of $120 (120% of $100). Suppose that during the first 180-day interval, you increased the payment amount to $110. During the next 180-day interval (starting September 7), you can only increase the amount of the payment to a maximum of $132 (120% of $110).
Integrating Recurring Payments Recurring Payments Notifications 6 Recurring payments IPN messages and email Event IPN Buyer Email Profile successfully created Yes Yes Profile creation failed Yes Yes Profile canceled from paypal.
6 74 Integrating Recurring Payments Recurring Payments Notifications April 2012 PayPal Payments Pro Integration Guide
A Getting Started With the PayPal Name-Value Pair API The PayPal Name-Value Pair (NVP) API provides parameter-based association between request and response fields of a message and their values. The request message is sent via the API from your website and a response message is returned by PayPal using a client-server model in which your site is a client of the PayPal server.
A Getting Started With the PayPal Name-Value Pair API PayPal API Client-Server Architecture PayPal Name-Value Pair API Requests and Responses To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal NVP server and interpret the response. In the following diagram, your website generates a request. The request is executed on a PayPal server and the response is returned to your site.
Getting Started With the PayPal Name-Value Pair API Obtaining API Credentials A 1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other setup actions also can be performed by this API operation. 2. Invoke additional API operations after receiving the buyer’s permission on PayPal, for example, GetExpressCheckoutDetails or DoExpressCheckoutPayment.
A Getting Started With the PayPal Name-Value Pair API Obtaining API Credentials Creating an API Signature An API signature consists of an API username along with an associated API password and signature, all of which are assigned by PayPal. You need to include this information whenever you execute a PayPal API operation. You must have a PayPal Business account to create a signature. To create an API signature: 1. Log in to PayPal, then click Profile under My Account. 2. Click My selling tools. 3.
Getting Started With the PayPal Name-Value Pair API Obtaining API Credentials A Creating an API Certificate Create an API certificate only if your website requires it. Typically, you want to create an API signature for your credentials instead. You must have a PayPal Business account to create an API certificate. NOT E : The certificate for API credentials is not the same as an SSL certificate for your website; they are not related to each other.
A Getting Started With the PayPal Name-Value Pair API NVP Format 8. Rename this file to something familiar, such as paypal_live_cert.pem. It is not necessary to keep the .txt file extension. Be sure to remember where you save the file. After Completing This Task: If you use the PayPal SDK for Java, the PayPal SDK for .NET, or the PayPal SDK for Classic ASP, you must encrypt your certificate in PCKS12 format. If you use the PayPal SDK for .
Getting Started With the PayPal Name-Value Pair API Creating an NVP Request A A method specifies the PayPal operation you want to execute, and each method is associated with a version. Together, the method and version define the exact behavior of the API operation. Typically, the behavior of an API operation does not change between versions; however, you should carefully retest your code whenever you change a version. To specify a method and version number: 1.
A Getting Started With the PayPal Name-Value Pair API Creating an NVP Request To enable PayPal to authenticate your request: 1. Specify the API username associated with your account. USER=API_username 2. Specify the password associated with the API username. PWD=API_password 3. If you are using an API signature and not an API certificate, specify the API signature associated with the API username. SIGNATURE=API_signature 4.
Getting Started With the PayPal Name-Value Pair API Creating an NVP Request A should consistently URL-encode the complete API request; otherwise, you may find that unanticipated data causes an error. NOT E : An HTTP form is automatically URL-encoded by most browsers. For example, consider the following NVP string: NAME=Robert Moore&COMPANY=R. H.
A Getting Started With the PayPal Name-Value Pair API Executing NVP API Operations Executing NVP API Operations You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal API server, or by using cURL or another mechanism to provide secure access between the buyer’s browser and the PayPal API server. For example, you might implement a system in which the buyer’s browser remains a client of your server and your server becomes a client of the PayPal API server.
Getting Started With the PayPal Name-Value Pair API Responding to an NVP Response A Responding to an NVP Response The Name-Value Pair response consists of the answer to the request as well as common fields that identify the API operation and how it was executed. The following diagram shows fields in the response to a PayPal NVP API operation: Common Response Fields The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation.
A Getting Started With the PayPal Name-Value Pair API Responding to an NVP Response Format of an Error Response Response Fields on Error ACK=notSuccess&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=VersionNo& BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage& L_LONGMESSAGE0=longMessage& L_SEVERITYCODE0=severityCode Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.
B Implementing 3-D Secure Transactions (UK Only) Website Payments Pro allows UK merchants to pass 3-D Secure™ authentication data to PayPal for debit and credit cards processed with the DoDirectPayment API request. Updating your site with 3-D Secure enables your participation in the Verified by Visa and MasterCard SecureCode programs. NOT E : A US or Canadian merchant can implement 3-D Secure; however, the authentication data is ignored by PayPal.
B Implementing 3-D Secure Transactions (UK Only) Integration Overview 3-D Secure is not supported for direct Recurring Billing and Reference Transactions. Cards that require 3-D Secure authentication cannot use these APIs; however, cards where 3-D Secure is optional can continue to process transactions without authentication. If you use either of these features in your current integration, you must exclude the Maestro card type from the available options.
Implementing 3-D Secure Transactions (UK Only) Transaction Processing NOT E : B Cardinal Commerce will be available to schedule an integration meeting with you and will support you with your Cardinal Centinel Integration requirements. PayPal page for Cardinal Commerce merchant registration Transaction Processing Integrating Cardinal Centinel and 3-D Secure with your PayPal transaction processing is fairly straightforward.
B Implementing 3-D Secure Transactions (UK Only) Transaction Processing URL to Handle Issuer’s Response You must establish a page on your site whose URL can receive a form POST from the card’s issuer that contains two fields, PaRes and MD. The page must then request cmpi_authenticate as described in the next section. Your page’s URL is referred to as TermURL.
Implementing 3-D Secure Transactions (UK Only) Transaction Processing B – Error information: Evaluate and take appropriate action if nonzero. Refer to the Thin Client Integration Guide for error codes, descriptions, explanations, and recommended actions. – Cardinal transaction information that you will pass to other requests: TransactionId, Enrolled, Payload, and EciFlag. – ACSUrl: If Enrolled=Y, this contains the URL for the card issuer’s (bank’s) authentication site.
B Implementing 3-D Secure Transactions (UK Only) Transaction Processing 3-D Secure Fields for Direct Payment Transaction Requests If the cardholder is authenticated, or if not authenticated for valid reasons such as the authentication service being unavailable or the cardholder not being enrolled, execute the direct payment transaction request with the following additional fields: 92 NVP/SOAP Field SOAP Field Description VERSION Version Set to 59.0.
Implementing 3-D Secure Transactions (UK Only) Website Setup B Flow of field values among requests and responses. Not all fields are shown. Example DoDirectPayment request The following example shows the additional fields required for 3-D Secure transactions; refer to the DoDirectPayment documentation for all required fields. METHOD=DoDirectPayment&...&ECI3DS=5&CAVV=OTJlMzViODhiOTllMjBhYmVkMGU =&AUTHSTATUS3DS=Y&MPIVENDOR3DS=Cardinal&VERSION=59.
B Implementing 3-D Secure Transactions (UK Only) Examples Examples The following examples outline the transaction process for three basic situations. Example 1: Successful 3-D Secure Authentication In this example, the cardholder’s issuer uses 3-D Secure and the authentication is successful: 1. Construct your message for cmpi_lookup. 2. Review the response from cmpi_lookup. Ensure that all of the following are true: – ErrorNo=0 – Enrolled=Y – ACSUrl has content; for example: https://www.
Implementing 3-D Secure Transactions (UK Only) Testing B 3. Using HTTP Form POST, redirect the cardholder to the issuer’s URL that was provided in ACSUrl. Ensure that the PaReq has the data from the field PayLoad, from the cmpi_lookup response. 4. Send the response (redirect) from the issuer’s HTTP Form POST to Cardinal using the cmpi_authenticate message to determine how to proceed with the transaction. 5. The cmpi_authenticate response determines how to proceed.
B Implementing 3-D Secure Transactions (UK Only) cmpi_lookup API cmpi_lookup API The cmpi_lookup request is a Cardinal Centinel request. This section lists required fields and responses as a convenience for you. Refer to the Cardinal Thin Client Integration Guide Payer Authentication document for details and the most current information. cmpi_lookup Request cmpi_lookup Request Fields Field Description MsgType (Required) Must be cmpi_lookup. Version (Required) Must be 1.7.
Implementing 3-D Secure Transactions (UK Only) Issuer Authentication Fields Field Description TransactionId Centinel transaction identifier. Identifies the transaction within Centinel. Enrolled Status of authentication eligibility. If not Y, then the cardholder is not eligible for authentication. Possible values are: Y: Enrolled N: Not enrolled U: Cardholder authentication unavailable.
B Implementing 3-D Secure Transactions (UK Only) cmpi_authenticate API Issuer Authentication Response When the issuer has completed its authentication processing, it calls the URL that you provided to it in TermURL. The issuer returns the following fields. Issuer Authentication Response Fields Field Description PaRes Authentication information to pass to cmpi_authenticate. MD Copy of MD sent by merchant. cmpi_authenticate API The cmpi_authenticate request is a Cardinal Centinel request.
Implementing 3-D Secure Transactions (UK Only) cmpi_authenticate API Field Description ErrDesc Empty if there is no error, otherwise, describes the error. PAResStatus The outcome of the issuer’s authentication. Possible values are: Y: Successful; merchant is protected. N: Failed; no protection. U: Unable to complete; no protection. A: Successful; merchant is protected. Cavv A random sequence of characters; this is the encoded authentication.
B 100 Implementing 3-D Secure Transactions (UK Only) cmpi_authenticate API April 2012 PayPal Payments Pro Integration Guide
