CyberSource PayPal Services Implementation Guide

Transcription

1 CyberSource PayPal Services Implementation Guide Simple Order API SCMP API September 2015 CyberSource Corporation HQ P.O. Box 8999 San Francisco, CA Phone:

2 CyberSource Contact Information For general information about our company, products, and services, go to For sales questions about any CyberSource Service, or call or (toll free in the United States). For support information about any CyberSource Service, visit the Support Center at Copyright 2015 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not be interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource. Restricted Rights Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS and in similar clauses in the FAR and NASA FAR Supplement. For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Trademarks CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and echeck.net are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. 2

3 Contents CONTENTS Recent Revisions to This Document 7 Chapter 1 Introduction 8 About PayPal Payments 8 PayPal Payments 8 Payments Through the Hosted Order Page 8 Payments Through an API 9 Regular Payments 9 Preapproved Payments 11 Billing Agreements 12 PayPal Credits 13 Order Tracking with an API 14 Reconciliation IDs and Transaction Reference Numbers 14 Request IDs 14 Transaction Reply Information 15 Information from PayPal: Reply POST when Creating a Billing Agreement 15 Information from PayPal: Payment Data Transfer (PDT) 15 Information from PayPal: Instant Payment Notification (IPN) 16 Regular Payments 16 Preapproved Payments 17 Information from CyberSource: Reports 17 Information from CyberSource: Transaction Details in the Business Center 18 PayPal Messages 19 CyberSource Messages 19 Chargebacks 21 Additional Documentation 22 PayPal References 22 CyberSource Guides 22 PayPal Services Implementation Guide September

4 Contents Chapter 2 Setting Up Your System 23 Opening and Configuring Your PayPal Account 23 Settings for Hosted Order Page and API 24 Disabling Notifications 24 Disabling Electronic Checks 24 Setting Your Credit Card Statement Name 25 Entering the IPN URLs 26 Settings for API Users Only 29 Enabling API Access 29 Enabling Auto Return 32 Enabling Automatic Funds Transfer 33 Enabling the Settlement File 33 Configuring Your CyberSource Account 34 Merchants Using the API 34 Merchants Using the Hosted Order Page 35 All Merchants 35 Chapter 3 Requesting Services with the Simple Order API 37 Creating Buttons 37 Requesting the Service 37 PayPal s HTML Variables for a Regular Payment Button 37 Sending the Shipping Address for a Regular Payment Button 39 Specifying Shipping and Handling Charges for a Regular Payment Button 39 Specifying Tax for a Regular Payment Button 40 Interpreting CyberSource s Reply 41 Receiving PayPal s POST Response 42 Request Fields 43 Reply Fields 55 Processing a Preapproved Payment 56 Request Fields 57 Reply Fields 60 Canceling or Updating a Billing Agreement 63 Request Fields 64 Reply Fields 65 Processing a Credit 67 Request Fields 67 Reply Fields 69 Reason Codes 70 Testing 71 PayPal Services Implementation Guide September

5 Contents Chapter 4 Requesting Services with the SCMP API 72 Creating Buttons 72 Requesting the Service 72 PayPal s HTML Variables for a Regular Payment Button 72 Sending the Shipping Address for a Regular Payment Button 74 Specifying Shipping and Handling Charges for a Regular Payment Button 74 Specifying Tax for a Regular Payment Button 75 Interpreting CyberSource s Reply 76 Receiving PayPal s POST Response 77 Request-Level Fields 78 Offer-Level Fields 88 Reply Fields 90 Reply Flags 91 Processing a Preapproved Payment 92 Request-Level Fields 92 Offer-Level Fields 94 Reply Fields 95 Reply Flags 99 Canceling or Updating a Billing Agreement 99 Request-Level Fields 100 Reply Fields 100 Reply Flags 102 Processing a Credit 102 Request-Level Fields 103 Offer-Level Fields 104 Reply Fields 105 Reply Flags 106 Testing 107 Chapter 5 Creating a Shopping Cart Button 108 Appendix A Examples for the Simple Order API 110 Name-Value Pair Examples 111 Creating a Regular Payment Button 111 Creating a Billing Agreement Button 113 Processing a Preapproved Payment 115 Updating a Billing Agreement 116 Processing a Credit 116 Creating a Shopping Cart Button 117 PayPal Services Implementation Guide September

6 Contents XML Examples 118 Creating a Regular Payment Button 118 Creating a Billing Agreement Button 121 Processing a Preapproved Payment 123 Updating a Billing Agreement 125 Processing a Credit 126 Creating a Shopping Cart Button 127 Appendix B Examples for the SCMP API 128 Creating a Regular Payment Button 128 Creating a Billing Agreement Button 132 Processing a Preapproved Payment 134 Updating a Billing Agreement 136 Processing a Credit 138 Creating a Shopping Cart Button 139 Appendix C PayPal Reply Variables 140 PDT Reply Variables 140 Reply Variables for Creating a Billing Agreement 141 IPN Variables for Regular Payments 144 IPN Variables for Preapproved Payments 151 Appendix D Product Codes 152 Index 153 PayPal Services Implementation Guide September

7 Recent Revisions to This Document REVISIONS Release September 2015 August 2013 September 2012 Changes Updated the URL for accessing the CyberSource test server. See "Testing," page 107 and "Examples for the SCMP API," page 128. Removed incorrect information about Customer Support. Updated the information about request tokens. This revision contains only editorial changes and no technical updates April 2011 Updated the PayPal account setup information in "Enabling API Access," page 29. June 2010 Added Cybersource API usernames: Production: paypal_cybersource_api1.cybersource.com Testing: cybersource_paypal_api1.cybersource.com May 2010 Added the link-to-request fields: Simple Order API See linktorequest in Table 4, page 43 and Table 10, page 67. SCMP API See link_to_request in Table 15, page 78 and Table 19, page 92. PayPal Services Implementation Guide September

8 Introduction CHAPTER 1 About PayPal Payments If you are not already familiar with how PayPal works, consider opening a personal PayPal account to understand the customer s experience. In general, a customer opens a PayPal account and adds one or more funding sources, such as a credit card, or an electronic checking account. When the customer chooses to pay with PayPal, they must choose which funding source to use for the payment. If the customer receives payments and accumulates stored value in their PayPal Account, they may also choose to pay with those stored funds. For more information, go to Before you can process any PayPal payments, you must open and configure a PayPal business account and configure your CyberSource account to use PayPal as described in Chapter 2, "Setting Up Your System," on page 23. When you open your PayPal business account, PayPal assigns you a PayPal account manager who will assist you with configuring your PayPal account. PayPal Payments Payments Through the Hosted Order Page To begin processing regular PayPal orders through the Hosted Order Page, you only need to configure your CyberSource account. See Chapter 2, "Setting Up Your System," on page 23. The customer completes the billing and shipping fields on the order form and clicks the Buy button. At that time, you send the order information to CyberSource, as you would through the API, and CyberSource redirects the order information to PayPal s Web site so that the transaction can be completed. CyberSource passes to PayPal the request ID, the success and cancellation URLs, your billing information, your address, the amount of the transaction, and the currency. PayPal Services Implementation Guide September

9 Chapter 1 Introduction When using the Hosted Order Page, the transaction process is similar to that used by the API for regular payments ("Payments Through an API," page 9) except that by default the customer is returned to these Hosted Order Page success and cancellation pages: If the customer completed the transaction successfully, the customer is returned to the same success page as for card or check transactions. If the customer did not complete the transaction, or if the transaction failed, the customer is returned to the order form to choose another form of payment. In addition, if you configure the Hosted Order Page to do so, CyberSource sends to you and to your customer an receipt for the order. See the samples in "CyberSource Messages," page 19. Payments Through an API You can process these types of PayPal payments: Regular payments This is a standard payment for goods and services Preapproved payments These are periodic payments that you can process without involving the customer once you have established a billing agreement with the customer You can also process credits (refunds) for both types of payments. Regular Payments This section describes the flow for accepting regular PayPal payments at your site. See Figure 1, page 10 for a diagram of the payment flow. The customer shops at your Web store and selects items to purchase. You collect the billing and shipping addresses and calculate tax and shipping. 1 The customer chooses PayPal as the payment type from the list of payment types you provide. 2 You send the order information to CyberSource in a request for the Button Create Service, indicating that you want a button for a regular PayPal payment. 3 In the reply, you receive the button (a self-contained form) containing the secure payment data PayPal requires. Note that the service returns to you two buttons: an encrypted version of the button (to use in production) and an unencrypted version (to use when testing or troubleshooting). 4 The customer clicks the button, which POSTs the secure payment data to PayPal while taking the customer to the PayPal Web site to log in and authorize the payment. PayPal Services Implementation Guide September

10 Chapter 1 Introduction 5 Depending on the result: PayPal directs the customer to the success page. If the customer clicks cancel, PayPal directs the customer to the cancellation page, which instructs the customer to choose a new payment type. Figure 1 Processing a Regular PayPal Payment After PayPal processes the payment: PayPal sends you an notification of the payment (you can turn this off if you do not want to get the s). PayPal sends the customer an receipt for the payment. If you are using the Hosted Order Page, CyberSource sends to you and to the customer the receipts that you configured. PayPal Services Implementation Guide September

11 Chapter 1 Introduction Your PayPal account reflects the payment. CyberSource receives PayPal's Instant Payment Notification (IPN) message for the payment. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. CyberSource forwards you the IPN message if you configure your CyberSource account for this. See "Configuring Your CyberSource Account," page 34. The information from the IPN is included in CyberSource s Payment Events Report. See "Information from CyberSource: Reports," page 17. The details for the payment are available for you to view in the Business Center. See "Information from CyberSource: Transaction Details in the Business Center," page 18. Preapproved Payments To process preapproved PayPal payments, you must first create a billing agreement between the customer and yourself. The main agreement items include the maximum allowed payment amount, and the description of the payments. After the customer accepts the terms of the agreement, you are then allowed to process preapproved payments and withdraw the funds from the customer's PayPal account without further customer interaction. The general flow in Steps 1 5 below is very similar to the general flow for processing a regular payment. See Figure 1, page 10 for reference. 1 The customer chooses PayPal for processing preapproved payments. You establish a contract with your customer that includes the terms of the billing agreement and the maximum amount that you will process a preapproved payment for. 2 You send the billing agreement information to CyberSource in a request for the Button Create Service, indicating that you want a button for a billing agreement. 3 In the reply, you receive the button (a self-contained form) containing the billing agreement data. Note that the service returns to you two buttons: an encrypted version of the button (to use in production) and an unencrypted version (to use when testing or troubleshooting). 4 The customer clicks the button, which POSTs the billing agreement data to PayPal while taking the customer to the PayPal Web site to log in, view the terms of the agreement, and approve the agreement. 5 When the customer approves the agreement, PayPal sends the customer to your Web site and POSTs information about the agreement, including an HTML variable called mp_id. This variable contains an identifier associated with that billing agreement. You must store the identifier because you need it to process preapproved payments for this customer. The customer also receives the identifier in the confirmation for the contract. 6 Later, when you want to process a preapproved payment for the customer, you use CyberSource s Preapproved Payment Service and include the billing agreement identifier in the request. PayPal Services Implementation Guide September

12 Chapter 1 Introduction After the customer accepts the billing agreement: PayPal sends the customer an notification for the new billing agreement. CyberSource receives PayPal's Instant Payment Notification (IPN) message for the billing agreement creation. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. CyberSource forwards you the IPN message if you configure your CyberSource account for this. See "Configuring Your CyberSource Account," page 34. The information from the IPN is included in CyberSource s Payment Events Report. See "Information from CyberSource: Reports," page 17. The details for the billing agreement are available for you to view in the Business Center. See "Billing Agreements," page 12. After a preapproved payment is processed: PayPal sends the customer an notification of the payment CyberSource receives PayPal's Instant Payment Notification (IPN) message for the preapproved payment. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. CyberSource forwards you the IPN message if you configure your CyberSource account for this. See "Configuring Your CyberSource Account," page 34. The information from the IPN is included in CyberSource s Payment Events Report. See "Information from CyberSource: Reports," page 17. The details of the preapproved payment are available for you to view in the Business Center. See "Information from CyberSource: Transaction Details in the Business Center," page 18. Billing Agreements You can cancel a preapproved payment billing agreement or update the description of a billing agreement by using CyberSource s API. You may not update the agreed-to maximum allowed payment amount. After you cancel or update a billing agreement: CyberSource receives PayPal's Instant Payment Notification (IPN) message for the cancellation or update. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. CyberSource forwards you the IPN message if you configure your CyberSource account for this. See "Configuring Your CyberSource Account," page 34. The information from the IPN is included in CyberSource s Payment Events Report. See "Information from CyberSource: Reports," page 17. The details of the billing agreement are available for you to view in the Business Center. To view a billing agreement s status, you must search for the transaction you used to created the billing agreement. The bottom of the details page for the transaction shows the billing agreement details, including whether the agreement is active or canceled. Currently you cannot search by using the billing agreement PayPal Services Implementation Guide September

13 Chapter 1 Introduction identifier (mp_id). The easiest alternate way is to search by using the customer s name, the merchant reference number, or the type of application (PayPal Billing Agreement). PayPal Credits You can perform only one credit for an order, for either a partial amount or the full amount of the payment. You can refund a customer s money through the Business Center or by using an API to request the PayPal credit service: Business Center Search for and retrieve the original payment request from the database by using the request ID or another identifier for the payment. Then click a button in the Business Center interface to request the credit. You must perform the credit within 60 days of the payment request. PayPal credit service Provide the request ID from the original payment so that CyberSource can locate the payment information in the database. You must perform the credit within 60 days of the payment request. After a credit is processed: CyberSource receives PayPal's Instant Payment Notification (IPN) message for the credit. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. CyberSource forwards you the IPN message if you configure your CyberSource account for this. See "Configuring Your CyberSource Account," page 34. The information from the IPN is included in CyberSource s Payment Events Report. See "Information from CyberSource: Reports," page 17. The details of the credit are available for you to view in the Business Center. See "Information from CyberSource: Transaction Details in the Business Center," page 18. PayPal Services Implementation Guide September

14 Chapter 1 Introduction Order Tracking with an API For general information about order tracking, see Getting Started with CyberSource Advanced. Reconciliation IDs and Transaction Reference Numbers The following table lists the field names for the PayPal reconciliation IDs and transaction reference numbers in the API reply messages. Table 1 Reconciliation IDs and Transaction Reference Numbers in Replies Service Button create Preapproved payment Preapproved update Credit Field Names Simple Order API: paypalbuttoncreatereply_reconciliationid SCMP API: paypal_button_create_trans_ref_no Simple Order API: paypalpreapprovedpaymentreply_reconciliationid SCMP API: paypal_preapproved_payment_trans_ref_no Simple Order API: paypalpreapprovedupdatereply_reconciliationid SCMP API: paypal_preapproved_update_trans_ref_no Simple Order API: paypalcreditreply_reconciliationid SCMP API: paypal_credit_trans_ref_no Request IDs For all PayPal services, the request ID is returned in the reply message: requestid for the Simple Order API request_id for the SCMP API The field names for the PayPal request IDs in the credit request messages are: paypalcreditservice_paypalpaymentrequestid for the Simple Order API paypal_payment_request_id for the SCMP API PayPal Services Implementation Guide September

15 Chapter 1 Introduction Transaction Reply Information Information from PayPal: Reply POST when Creating a Billing Agreement After you create a billing agreement button and the customer goes to the PayPal site to approve the agreement, PayPal POSTs information to you about the event while returning the customer to your Web site. See Step 5 in "Preapproved Payments," page 11. The POST includes the billing agreement ID that you need to store. For a complete list of the HTML variables you can receive in the POST, see "Reply Variables for Creating a Billing Agreement," page 141. Information from PayPal: Payment Data Transfer (PDT) PayPal s Payment Data Transfer is an optional feature you can use if it fits your implementation. You use PDT to display payment transaction details to the customer when they are redirected to your site after completing a regular payment at PayPal s site. If you want to use PDT, you must enable Auto Return. See "Enabling Auto Return," page 32. You might choose to use PDT because it is one way to determine whether to ship the goods. Note that if the customer uses a delayed payment type such as an electronic check, the PDT information will not be sufficient because it takes typically several days before the check clears. Another disadvantage of PDT is that it is possible that the customer will close the browser before the redirect to your site is complete, causing you to miss receiving the PDT information. The information you receive with PDT is also available in CyberSource s reports and in the Instant Payment Notification message. CyberSource recommends that you use one of these methods instead of PDT if you need a reliable order fulfillment indicator. For information about setting up and using PDT, see PayPal s Merchant User Manual and Integration Guide. For information about the content of the PDT reply variables that you receive, see "PDT Reply Variables," page 140. PayPal Services Implementation Guide September

16 Chapter 1 Introduction Information from PayPal: Instant Payment Notification (IPN) PayPal s Instant Payment Notification (IPN) provides immediate notification about your payments and billing agreements and any events relating to them. CyberSource automatically receives all of the IPN messages for your PayPal account and uses the information to populate CyberSource s reports. Because CyberSource receives your IPN messages for you, you do not need to set up your PayPal account to receive them. You can configure your CyberSource account so that you are forwarded your IPN messages as soon as CyberSource receives them. You might want to do this if you need to ship the ordered goods immediately, and you cannot wait for the confirmation that comes in the CyberSource reports. When you configure your CyberSource account, you give CyberSource the secure URL where you want to receive the IPN messages. Important The Payment Events Report, which is described in "Information from CyberSource: Reports," page 17, includes the information from every IPN message that is forwarded to you. If the system that receives your IPN messages is not available, PayPal will repeat forwarding each IPN message at specific intervals until your system receives it or until PayPal s system reaches its retry limit. Each of these instances will be included in the Payment Events Report, so you will see multiple occurrences of the same information in the report if your system does not receive the IPN message the first time it is forwarded to you. To use IPN message forwarding, your server certificate must be issued by a Certificate Authority (CA) that is known to CyberSource. If it is not, CyberSource cannot authenticate your server certificate during the handshake with your server. CyberSource supports all of the CA s that are generally used. Check with CyberSource Customer Service to make sure your certificate meets these requirements. Regular Payments For regular payments, you receive an IPN message when these events occur: Payment Clearing of an electronic check Reversal of a payment Cancelation of a reversal of a payment Refund of a payment See "IPN Variables for Regular Payments," page 144 for a list of IPN variables you receive for a regular payment. PayPal Services Implementation Guide September

17 Chapter 1 Introduction Preapproved Payments For preapproved payments, you receive an IPN message when these events occur: Creation of a new billing agreement Update of a billing agreement Cancellation of a billing agreement Impending expiration of a customer s funding source Removal by the customer of the last PayPal funding source associated with the billing agreement Locking or restricting of the customer s PayPal account See "IPN Variables for Preapproved Payments," page 151 for a list of IPN variables you receive for preapproved payments. To configure your IPN settings, see "Entering the IPN URLs," page 26. Information from CyberSource: Reports The CyberSource reports listed below include information about your PayPal transactions. The information in the reports comes from your API requests, the Hosted Order Page, and from the IPN messages that PayPal sends. Payment Events Report Shows the latest status of your PayPal payments and credits and whether you can fulfill the order. It is a daily report that includes any new information from the past 24 hours that PayPal has about any of your transactions. For example, when you request a payment, if the payment is pending (which happens if the customer pays with an electronic check), the transaction is included in the report for the first time with a status of pending. The next time the transaction is included in the report (which could be several days later), it will have a status of completed or denied, which indicates whether you can ship the goods. The transaction will be included again in the report if other events occur. For example, it is included again if the customer initiates a reversal or if you initiate a refund. For billing agreements, the Processor Message field in the report contains the billing agreement identifier, PayPal s reason code for the event and a description of the event. See "reason_code," page 143. PayPal Services Implementation Guide September

18 Chapter 1 Introduction Note If you perform any PayPal transactions outside of the CyberSource interface, the IPN messages for those transactions will still be forwarded to CyberSource. The data from those transactions will be included in the Payment Events Report but not in the Business Center. To reduce inconsistency within your transaction management system, you should perform all of your PayPal transactions through CyberSource. The Payment Events Report includes the information from every IPN message that is forwarded to you. If the system that receives your IPN messages is not available, PayPal will repeat forwarding each IPN message at specific intervals until your system receives it or until PayPal s system reaches its retry limit. Each of these instances will be included in the Payment Events Report, so you will see multiple occurrences of the same information in the report if your system does not receive the IPN message the first time it is forwarded to you. Payment Submission Detail Report Lists the PayPal payments and credits that you process in a given day. Payment Batch Summary Report Summarizes the amount of your PayPal payments in each currency. Payment Invoice Summary Report Summarizes the transactions that are included on your CyberSource invoice. If you are already subscribed to these reports, then you will automatically start to see PayPal transactions in the reports. If you are a new user of these reports, you can subscribe to and obtain the reports in the Business Center. For general information about the reports, see the online help in the Business Center. For detailed information about the Payment Events Report and Payment Submission Detail Report, see the Reporting Developer s Guide. When reconciling, you may also want to use PayPal s Settlement File. See "Enabling the Settlement File," page 33 for more information. Information from CyberSource: Transaction Details in the Business Center You can view the details of your PayPal transactions in the Business Center just as you can for other payment types. You can search for transactions by date, application type (PayPal Billing Agreement, PayPal Button Create, PayPal Credit, PayPal Payment, and PayPal Preapproved Payment), customer name, and other transaction identifiers. To learn how to view the details of a billing agreement, see "Billing Agreements," page 12. PayPal Services Implementation Guide September

19 Chapter 1 Introduction To find transactions processed with the Hosted Order Page, you need to search for all transactions. These transactions will be identified in the search results and search details as PayPal Button Create. PayPal Messages You automatically receive notifications for any successful payments, canceled payments, and pending payments. You can turn off these s by disabling them in your PayPal profile. For more information, see "Disabling Notifications," page 24. CyberSource Messages If you use the Hosted Order Page, you can configure in the settings page notification messages in addition to those sent by PayPal: Merchant s Purchase Data merchantid=infodev orderpage_serialnumber= ordernumber= orderamount=9 ordercurrency=usd ordernumber_publicsignature=yy09ermdwbyekp1tpebgc1bdurk= orderamount_publicsignature=oozcyv29ovgjsjwbcw0nwfxxtms= ordercurrency_publicsignature=3fgv79otz8e6cnjru2pzkgfkyoy= decision_publicsignature=aqpyvf584wip6aq8jj8mil5juve= billto_street1=1111 Sample Avenue billto_city=your Town billto_state=ca billto_country=us billto_postalcode=99999 billto_firstname=john billto_lastname=doe requestid= decision=accept reasoncode=100 paymentoption=paypal orderpage_transactiontype=authorization PayPal Services Implementation Guide September

20 Chapter 1 Introduction Merchant s Purchase Confirmation Sample Header Purchase Description Payment Details Order Number: Subtotal: 9.00 Tax: 0.00 Total: 9.00 For Support, contact: Your Merchant [email protected] Order Details Payment Type: paypal Customer ID: Billing Address: John Doe 1111 Sample Avenue Your Town, CA Return Codes Result Code: Request was processed successfully. Transaction Details Transaction Type: authorization Transaction Source: Hosted Order Page Reconciliation ID: Merchant Defined Data Field 1: Fast shipping Field 2: Gift Thank you, and please visit us again! PayPal Services Implementation Guide September

21 Chapter 1 Introduction Customer s Receipt Sample Header Purchase Description Payment Details Order Number: Subtotal: 9.00 Tax: 0.00 Total: 9.00 For Support, contact: Your Merchant [email protected] Order Details Payment Type: paypal Customer ID: Billing Address: John Doe 1111 Sample Avenue Your Town, CA Thank you, and please visit us again! Chargebacks PayPal offers several services related to chargebacks: If the customer chooses a credit card as the funding source for the PayPal payment, they have the normal chargeback dispute rights. If the customer disputes the charge, PayPal performs the initial chargeback processing and contacts you for documentation. PayPal offers a Buyer Complaint Process that is applicable to all purchases, regardless of the funding source. When a customer files a complaint, PayPal performs an investigation and contacts you for documentation. PayPal also provides a service called the Seller Protection Plan (SPP), which helps protect merchants against chargebacks due to fraud. The service is available only to qualifying merchants, and only for orders where the shipping address matches a confirmed address on file at PayPal. CyberSource indicates whether the address is confirmed or unconfirmed in the list of transaction details, which you can view by searching for the transaction in the Business Center. PayPal Services Implementation Guide September

22 Chapter 1 Introduction For more information about these services, contact your PayPal Account Manager, or visit PayPal s Security Center (go to and click Security Center at the bottom of the page). Additional Documentation PayPal References The PayPal documents are available on the PayPal web site: Sandbox User Guide PayPal Sandbox test environment Merchant User Manual and Integration Guide Your PayPal profile setup, regular payments, Payment Data Transfer, and Instant Payment Notification Preapproved Payments Developer Guide and Reference Preapproved payments CyberSource Guides The CyberSource documents are available on the Support Center: Getting started Account management, technical resources, basics about the Simple Order API and SCMP API. See Getting Started with CyberSource Advanced. Business Center Configuring account settings and searching for order information. See the Business Center Overview. Hosted Order Page Payment order form hosted by CyberSource. See the Hosted Order Page User s Guide. Simple Order API API for accessing CyberSource services. See Credit Card Services for the Simple Order API. SCMP API API for accessing CyberSource services. See Credit Card Services for the SCMP API. Reporting Using the CyberSource reports. See the Reporting Developer s Guide. PayPal Services Implementation Guide September

23 Setting Up Your System CHAPTER 2 Opening and Configuring Your PayPal Account If you do not already have a PayPal business account, go to to open one. To configure your PayPal account, log in and click the Profile tab: This chapter describes the PayPal settings needed to make your PayPal and CyberSource accounts work together. To configure additional PayPal settings, see PayPal s Merchant User Manual and Integration Guide, which is available at PayPal Services Implementation Guide September

24 Chapter 2 Setting Up Your System Settings for Hosted Order Page and API Disabling Notifications If you do not want to receive an message every time a customer pays with PayPal at your store, you can turn off notifications. To do this, go to the Notifications page and disable notifications for I receive money with PayPal and I receive PayPal Website Payments and Instant Purchase. t Disabling Electronic Checks Depending on your business rules or the type of products you sell, you may not want to let customers use their electronic checking accounts when paying through PayPal. Checks typically take 3 to 4 business days to clear. Use the Business Center or the Payment Events Report to verify that a check has cleared. To disable acceptance of electronic checks, in the Payment Receiving Preferences page, disable echeck for PayPal Website Payments and Smart Logo payments. PayPal Services Implementation Guide September

25 Chapter 2 Setting Up Your System Setting Your Credit Card Statement Name Whenever a customer funds a payment with a credit card, your name will be included on the customer s credit card statement in the purchase description. Setting your credit card statement name helps reduce chargebacks and customer confusion. Note PayPal * is appended at the beginning of the credit card statement name. For example, YourCompany is included as PayPal *YourCompany. To set the credit card statement name, go to the Payment Receiving Preferences page. See the screen in "Disabling Electronic Checks," page 24. PayPal Services Implementation Guide September

26 Chapter 2 Setting Up Your System Entering the IPN URLs If you want to receive IPN notifications so that you can see the payment information in the Business Center, return to the Profile Summary page. You can return to this page to change the URL as necessary. Note Step 1 Click Instant Payment Notification Preferences. This page is displayed. PayPal Services Implementation Guide September

27 Chapter 2 Setting Up Your System Step 2 Click Edit. Step 3 Check the box and enter one of these URLs: For CyberSource s test environment: For CyberSource s production environment: PayPal Services Implementation Guide September

28 Chapter 2 Setting Up Your System Step 4 Click Save. You are ready to proceed to the next section. PayPal Services Implementation Guide September

29 Chapter 2 Setting Up Your System Settings for API Users Only Enabling API Access To process PayPal payments and credits through the CyberSource API, you must enable CyberSource to act on your behalf in the PayPal system. Step 1 Under Account Information, click the API Access link. PayPal Services Implementation Guide September

30 Chapter 2 Setting Up Your System Step 2 Click the Grant API Permission link. Step 3 For testing, enter cybersource_paypal_api1.cybersource.com, which is the CyberSource API account username. For live transactions, enter paypal_cybersource_api1.cybersource.com. Step 4 Click Lookup. PayPal Services Implementation Guide September

31 Chapter 2 Setting Up Your System Step 5 Select the permissions circled in red in the following figure and then click Add. PayPal Services Implementation Guide September

32 Chapter 2 Setting Up Your System Step 6 You can edit or view permissions from the Success page: Enabling Auto Return CyberSource recommends that you use PayPal s Auto Return, which returns the customer immediately to your Web site at the conclusion of the purchase. With Auto Return, the typical PayPal-hosted payment complete page is replaced with a page on your site, allowing you to control the customer s experience at the end of the purchase, and perform any follow-on sales or marketing activities. To enable Auto Return, go to the Website Payment Preferences page. You will need to provide the URL for the return page. For more information about Auto Return, see PayPal s Merchant User Manual and Integration Guide. PayPal Services Implementation Guide September

33 Chapter 2 Setting Up Your System You can override the Auto Return URL that you have specified by using a particular API field in your Button Create Service request. For more information, see the description of paypal_return in Table 4, page 43 (for the Simple Order API) or in Table 15, page 78 (for the SCMP API). Enabling Automatic Funds Transfer Typically, PayPal will deposit payments that you receive into your PayPal Business Account. However, PayPal can also automatically transfer the funds you receive from PayPal payments into a bank account that you designate. To enable this, contact your PayPal Account Manager. Enabling the Settlement File Your PayPal payments and credits will be reflected in your CyberSource reports. For many merchants, this is sufficient to support reconciliation. However, if you prefer additional detail for reconciliation, you might want to use PayPal s Settlement File. In particular, you might want to use it if you are accepting payments in multiple currencies, as it documents the exchange rate conversion. Contact your PayPal Account Manager for more information. PayPal Services Implementation Guide September

34 Chapter 2 Setting Up Your System Configuring Your CyberSource Account You need to configure your CyberSource account differently depending on the method that you choose to send your transaction requests to CyberSource. As of May 31, 2006, the configuration process differs slightly for existing and new merchants. Merchants Using the API The PayPal return fields paypal_return and paypal_cancel_return (Table 4, page 43 (Simple Order API) or Table 15, page 78 (SCMP API)) were optional. They are now required for API users. For information about integrating with CyberSource s API, see "Requesting Services with the Simple Order API," page 37 or "Requesting Services with the SCMP API," page 72. Existing merchants Your PayPal ID and IPN URL are transferred to the new implementation. You only need to configure the PayPal return fields if you have not so already. See "Information from PayPal: Instant Payment Notification (IPN)," page 16. New merchants You need to call CyberSource Customer Support to provide your PayPal ID and IPN URL. After that, you need to configure the PayPal return fields. PayPal Services Implementation Guide September

35 Chapter 2 Setting Up Your System Merchants Using the Hosted Order Page Merchants who use the Hosted Order Page cannot use the PayPal return fields. Existing merchants Your settings are transferred. Customers are now returned to the default Hosted Order Page receipt and decline pages. New merchants You need to call CyberSource Customer Support to be enabled for the Hosted Order Page. After that, you need to configure your Hosted Order Page settings: a b c d e f g In the Business Center, go to Settings > HOP Settings. Scroll to the Payment Types subsection. Check the box for PayPal. You can choose PayPal as sole form of payment or any of the other forms available. Enter your PayPal login ID. If you use the Hosted Order Page, leave this field blank. Complete the other configuration fields as necessary for your Hosted Order Page implementation. You can begin processing PayPal payments with the Hosted Order Page. Set the payment currencies and payment types. If you customize your order form, use the field paymentoption to indicate the type of payment: card, check, or paypal. You can also set the currencies you want to accept for each payment type. For more information, see the Hosted Order Page User s Guide. All Merchants Step 1 Enable cookies in your web browser. Open your web browser and follow the instructions appropriate for your browser. For Internet Explorer: a Select Tools > Internet Options > Privacy. b In the Settings section, move the slider to the bottom (Accept All Cookies). c Click Apply. d Click OK. For Netscape Communicator: a Select Edit > Preferences. b Click Advanced. c Check the box Accept All Cookies and click OK. PayPal Services Implementation Guide September

36 Chapter 2 Setting Up Your System Step 2 Send the shipping address When collecting information about the order, CyberSource recommends that you collect the shipping address information even though it is optional. PayPal will check the shipping address that you provide against the customer s list of confirmed addresses. If the address is one of the confirmed addresses, the transaction may be eligible for chargeback protection under PayPal s Seller Protection Policy. See PayPal s Security Center for more information. If PayPal returns to you a different address than that entered by the customer in the Hosted Order Page, use the address returned by PayPal when fulfilling the order. PayPal Services Implementation Guide September

37 Requesting Services with the Simple Order API CHAPTER 3 Creating Buttons The paypalbuttoncreateservice lets you create the following types of buttons: One for processing a regular payment with an aggregate amount for the order (PayPal s Buy Now button) Note PayPal also has a Shopping Cart button that uses individual item information and amounts instead of an aggregate order total. This chapter discusses how to create PayPal s Buy Now button. For information about requesting a Shopping Cart button, see Chapter 5, "Creating a Shopping Cart Button," on page 108. One for creating the billing agreement for preapproved payments For more information about regular and preapproved payments, see "PayPal Payments," page 8. Requesting the Service To request the service, send a request with paypalbuttoncreateservice_run=true. Use the paypalbuttoncreateservice_buttontype field to indicate which type of button you want. See Appendix A, "Examples for the Simple Order API," on page 110 for example requests. When creating a regular payment button, the only other ICS service you can include in the request is the Tax Calculation Service. For more information, see the Tax Calculation Implementation Guide. When creating a billing agreement button, do not include any other ICS services in the request. PayPal s HTML Variables for a Regular Payment Button The regular payment button (PayPal s Buy Now button) that CyberSource creates includes a list of HTML variables that give transaction information to PayPal and that control the display of the PayPal site when the customer goes there to approve the PayPal Services Implementation Guide September

38 Chapter 3 Requesting Services with the Simple Order API payment. CyberSource adds paypal_ before the name of each variable to create the corresponding CyberSource API field that you use when creating the button. For example, PayPal has a variable called return. The field you include in your request to CyberSource is paypal_return. See the paypal_... fields in Table 4, page 43. Not all of the available PayPal HTML variables are listed in Table 4; only the basic ones you need to process a payment are included. For the entire list of HTML variables available for use with a Buy Now button, see PayPal s Merchant User Manual and Integration Guide. If PayPal s guide lists any variables that you want to use that are not already listed in Table 4, simply add the corresponding paypal_<variable_name> field to your paypalbuttoncreateservice request to include that variable in the button. This also allows you to easily use any new Buy Now button variables that PayPal might create in the future. CyberSource does not validate the content of the HTML variable API fields that you send. Important For some of the available HTML variables, CyberSource automatically assigns values and does not need your input. Specifically, CyberSource sets the values for cmd, business, custom, invoice, and notify_url and does not provide corresponding API fields for you to use. If you send fields called paypal_cmd, paypal_business, paypal_custom, paypal_invoice, or paypal_notify_url in your request, the request will be rejected. Some of CyberSource s regular API fields for specifying amounts and item-level information are similar to or duplicate the function of some of PayPal s HTML fields. For example, PayPal has an HTML variable called amount. CyberSource has similar API fields called purchasetotals_grandtotalamount and item_#_unitprice (and one of these two are required in the paypalbuttoncreateservice request). CyberSource automatically populates the PayPal amount variable that is included in the button with a value based on the purchasetotals_grandtotalamount or item_#_unitprice values that you provide in your paypalbuttoncreateservice request. However, you could theoretically include paypal_amount in your request in addition to a purchasetotals_grandtotalamount or item_#_unitprice, because CyberSource allows you to pass most of the available PayPal variables generically as paypal_<variable name> through the CyberSource API. But you should not do this because CyberSource will then include two values for the amount variable in the button: one based on the purchasetotals_grandtotalamount or item_#_unitprice values, and one based on the paypal_amount field you sent. This might lead to unpredictable amount values being displayed at PayPal s site when the customer goes there to approve the payment. If a particular PayPal HTML variable is being populated by CyberSource based on the value you provide for a similar CyberSource API field, the description for that PayPal variable in Table 4, page 43 will say so. For example, see the description for paypal_ amount in the table. PayPal Services Implementation Guide September

39 Chapter 3 Requesting Services with the Simple Order API Sending the Shipping Address for a Regular Payment Button When creating a regular payment button, you should include the shipping address in the request even though it is optional. PayPal will check the shipping address you provide against the customer s list of confirmed addresses. If the address is one of the confirmed addresses, the transaction may be eligible for chargeback protection under PayPal s Seller Protection Policy. See PayPal s Security Center at for more information. If you do not send a shipping address in your request, CyberSource will not substitute the billing address for the shipping address when sending the information to PayPal. To determine if the shipping address was confirmed or unconfirmed, search for the transaction in the Business Center. The transaction details include whether the address was confirmed or unconfirmed. Specifying Shipping and Handling Charges for a Regular Payment Button CyberSource and PayPal both have methods for you to specify freight charges (shipping and handling charges). When creating a regular payment button for an order with freight charges, you need to choose which method you want to use to specify the freight amount. You might already be familiar with CyberSource s methods if you process other payment types with CyberSource. The following table describes your choices. CyberSource s methods override any PayPal profiled-based shipping and handling settings you have. Important You should choose one of these methods and not send CyberSource shipping and handling fields as well as PayPal HTML variables for shipping and handling. If you do, the customer may see unexpected amounts for the shipping and handling when they go to PayPal s site to approve the payment. PayPal Services Implementation Guide September

40 Chapter 3 Requesting Services with the Simple Order API Table 2 Methods for Specifying Shipping and Handling Charges Method CyberSource: Using a total freight amount CyberSource: Using an item for the freight amount PayPal: Using a profile-based freight amount PayPal: Overriding the profilebased freight amount Description If you are using CyberSource s purchasetotals_grandtotalamount field to give a total amount for the order, then you must use the purchasetotals_freightamount field to give the total shipping and handling for the order. CyberSource will map this to the PayPal HTML variable shipping. This method overrides any profile-based amount you have set. See below. If you are using item-level information instead of the purchasetotals_grandtotalamount field, you must create at least one separate item for the shipping and/or handling amounts. For more details, see the information about creating requests in Getting Started with CyberSource Advanced. CyberSource will sum the amounts for items where the item_#_productcode=shipping_ only or shipping_and_handling and assign the value to the PayPal HTML variable shipping. CyberSource will sum the amounts for items where the item_#_productcode= handling_ only and assign the value to the PayPal HTML variable handling. This method overrides any profile-based amount you have set. See below. You can configure your PayPal profile to use flat shipping and handling amounts based on the overall order total. See PayPal s Merchant User Manual and Integration Guide for more information. You can configure your PayPal account so that you can override the flat profile-based shipping and handling amounts by using specific HTML variables when creating the button. PayPal s shipping, handling, and shipping2 HTML variables let you do this. See the descriptions of the corresponding CyberSource API fields paypal_shipping, paypal_handling, and paypal_shipping2 in Table 4, page 43. Specifying Tax for a Regular Payment Button CyberSource and PayPal both have methods for you to specify the tax for an order. When creating a regular payment button for an order with tax, you need to choose which method you want to use to specify the tax amount. You might already be familiar with CyberSource s methods if you process other payment types with CyberSource. The following table describes your choices. CyberSource s methods override any PayPal profiled-based tax settings you have. Important You should choose one of these methods and not send CyberSource tax fields as well as PayPal HTML variables for tax. If you do, the customer may see unexpected amounts for the tax when they go to PayPal s site to approve the payment. PayPal Services Implementation Guide September

41 Chapter 3 Requesting Services with the Simple Order API Table 3 Methods for Specifying an Order s Tax Method CyberSource: Using a total tax amount CyberSource: Using an item-level tax amount PayPal: Using a profile-based tax amount PayPal: Overriding the profile-based tax amount Description If you are using CyberSource s purchasetotals_grandtotalamount field to give a total amount for the order, then you must use the purchasetotals_taxamount field to give the total tax for the order. This method overrides any profile-based amount you have set. See below. If you are using item-level information instead of the purchasetotals_ grandtotalamount field, you must specify the total tax for each item in item_#_ taxamount. See the information about items and grand totals in Getting Started with CyberSource Advanced. This method overrides any profile-based amount you have set. See below. You can configure your PayPal profile to use certain tax amounts based on the customer s country and state. See PayPal s Merchant User Manual and Integration Guide for more information. You can configure your PayPal account so that you can override the profile-based tax amount by using a the tax HTML variable when creating the button. See the description of the corresponding CyberSource API field paypal_tax in Table 4, page 43. Interpreting CyberSource s Reply CyberSource returns to you an encrypted version and an unencrypted version of the button in the paypalbuttoncreatereply_encryptedformdata and paypalbuttoncreatereply_unencryptedformdata fields. Use the encrypted version when in production and the unencrypted version when troubleshooting or testing your system. See Appendix A, "Examples for the Simple Order API," on page 110 for example replies. You insert the button into your HTML page like this: <html><body> <!-- Insert your page header --> Click PayPal Checkout to proceed with your PayPal payment. This will take you to the PayPal login page. <!-- Replace the "%s" below with the button, which is a self-contained form that CyberSource returns to you. --> %s </body></html> PayPal Services Implementation Guide September

42 Chapter 3 Requesting Services with the Simple Order API The encrypted version of the button looks similar to this: <form action=" method="post"><input type="image" src=" border="0" name="submit"><input type="hidden" name="cmd" value="_s-xclick"><input type="hidden" name="encrypted" value=" -----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM-----END PKCS7-----"</form> Note The encrypted information in the above example has been shortened for illustration. The actual length of the information is about characters. The unencrypted version of the button looks similar to this: <form action=" method="post"><input type="image" src=" border="0" name="submit"><input type="hidden" name="cmd" value="_sxclick"><input type="hidden" name="business" value="[email protected]"><input type="hidden" name="first_name" value="larry"><input type="hidden" name="last_name" value="smith"><input type="hidden" name="address1" value="37 Main St."><input type="hidden" name="address2" value="suite 2"><input type="hidden" name="city" value="bloomington"><input type="hidden" name="state" value="in"><input type="hidden" name="zip" value="47404"><input type="hidden" name="amount" value="0.00"><input type="hidden" name="tax" value="0"><input type="hidden" name="handling" value="0.00"><input type="hidden" name="shipping" value="0.00"><input type="hidden" name="item_number" value="123454"><input type="hidden" name="cancel_return" value=" type="hidden" name="undefined_quantity" value="1"><input type="hidden" name="quantity" value="5"><input type="hidden" name="return" value=" type="hidden" name="item_ name" value="book"><input type="hidden" name="shipping2" value="0.00"><input type="hidden" name="currency_code" value="usd"><input type="hidden" name="bn" value="cybersource"><input type="hidden" name="notify_url" value=" ipn"><input type="hidden" name="invoice" value=" "><input type="hidden" name="custom" value=" , ,001"></form> Receiving PayPal s POST Response If you are using PayPal s Payment Data Transfer (PDT), you receive a POST from PayPal when the customer is redirected back to your site after approving a regular payment. See "Information from PayPal: Payment Data Transfer (PDT)," page 15 for more information. The POST contains a variable called st that indicates whether you can fulfill the order. See "PDT Reply Variables," page 140 for a full list of information you receive. PayPal Services Implementation Guide September

43 Chapter 3 Requesting Services with the Simple Order API When a customer approves a billing agreement at PayPal s site, PayPal sends the customer back to your Web site while POSTing information about the billing agreement (note that this POST has nothing to do with whether you are using PDT). You must make sure to store the mp_id that you receive because that is the billing agreement identifier that you need to process preapproved payments for the customer later. For a complete list of the return variables you receive, see "PDT Reply Variables," page 140. Request Fields The following table lists the request fields for creating buttons. The table indicates whether to use each field when creating a regular payment or billing agreement button. Table 4 Button Create Request Fields Request Field Description Use With Button Required/ Optional Data Type & Length billto_city City of the billing address. Both Required String (50) billto_country billto_ Country of the billing address. Use the twocharacter ISO codes. See the Support Center for a list of codes. Customer s address, including the full domain name (for example, [email protected]). Both Required String (2) Both Optional String (255) billto_firstname Customer s first name. Both Required String (60) billto_lastname Customer s last name. Both Required String (60) billto_postalcode billto_state Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes. Both Both Required if country is U.S. or Canada Required if country is U.S. or Canada String (10) String (2) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

44 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button item_#_ productcode item_#_ productname item_#_productsku Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. If you set this to a value other than default, stored_ value, or any of the values related to shipping and/or handling, the item_#_ quantity, item_#_productname, and item_ #_productsku fields are required. Product s name. This information is not displayed in the button but is displayed on the transaction details screen in the Business Center. Required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is NOT used for the item_ name variable in the button; paypal_item_ name is used for that; see the field description in this table. You may include both item_#_ productname and paypal_item_name in the request. Product s identifier code. This information is not displayed in the button but is displayed in the transaction details screen in the Business Center. Required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is not used for the item_ number variable in the button; paypal_item_ number is used for that; see the field description in this table. You may include both item_#_productsku and paypal_item_ number in the request. Regular payment Regular payment Regular payment Required/ Optional Optional String (30) See description See description Data Type & Length String (30) String (30) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

45 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button item_#_quantity item_#_taxamount Quantity of the product being purchased. The default value is 1. Required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is NOT used for the quantity variable in the button paypal_ quantity is used for that; see the field description in this table. This field is used to calculate the value that goes into the amount variable in the button. You may include both item_#_quantity and paypal_ quantity in the request. The sum of these values for all of the items becomes the value for the tax variable in the button.this is the total tax to apply to the product. The value is NOT multiplied by item_ #_quantity. This value overrides any profile-based tax you have set. See "Specifying Tax for a Regular Payment Button," page 40 for more details. The item_#_taxamount field is additive. For example, if you send one item with unitprice of $10.00 and taxamount of $0.80, and you send another item with unitprice of $20.00 and taxamount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included. The item_#_taxamount and the item_#_ unitprice must be in the same currency. The value cannot be negative. Regular payment Regular payment Required/ Optional See description Data Type & Length Integer (10) Optional String (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

46 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button item_#_unitprice linktorequest Per-item price of the product. You must include either this field or purchasetotals_ grandtotalamount in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. This field is used to calculate the value that goes into the amount variable in the button. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the Simple Order API. Regular payment Regular payment Required/ Optional See description Data Type & Length String (15) Optional String (26) merchantid merchantreference Code paypal_amount Your CyberSource merchant ID. Use the same merchantid for evaluation, testing, and production. Merchant-generated order reference or tracking number. CyberSource suggests you use a unique value for each order or billing agreement. See the information about tracking orders in Getting Started with CyberSource Advanced. CyberSource suggests you do NOT use this in your request for a regular payment button as you will already be specifying a purchasetotals_grandtotalamount or item_#_unitprice which will be used to populate PayPal s amount variable in the button. See "PayPal s HTML Variables for a Regular Payment Button," page 37 for more information. Both Required String (30) Both Required String (50) Neither See description (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. N/A PayPal Services Implementation Guide September

47 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_cancel_ return paypal_customer_ paypal_handling paypal_item_name URL of the Web page to show the customer if the customer cancels the regular PayPal payment. Example: cancel.example.com. Customer s address, including the full domain name (for example, [email protected]). Do NOT use this field if you are using purchasetotals_freightamount or if you have an item with item_#_productcode= handling_only. CyberSource populates the handling variable in the button based on your values for these fields. If you are not using purchasetotals_ freightamount or an item for handling, paypal_handling becomes the value for the handling variable in the button. This is a flat handling charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 39 for more details. This becomes the value for the item_name variable in the button. This is the description of the item. If omitted, the customer will see a field where they can enter a description of the item. Note Although CyberSource has a similar API field (item_#_productname), the item_ name variable will NOT be populated based on CyberSource s item_#_productname field. You may include both paypal_item_ name and item_#_productname in the request. Regular payment Required String (255) Both Optional String (255) Regular payment Regular payment Required/ Optional Optional String (15) Optional Data Type & Length String (127) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

48 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_item_ number paypal_lc paypal_mp_cycle_ start paypal_mp_desc This becomes the value for the item_ number variable in the button. It is not displayed to the customer, but it is passed back to you upon completion of the payment. If omitted, it is not passed back to you. Note Although CyberSource has a similar API field (item_#_productsku), the item_ number variable will NOT be populated based on CyberSource s item_#_ productsku field. You may include both paypal_item_number and item_# _ productsku in the request. Locale (language) for the billing agreement pages. Use the two-character ISO country codes. Defines the starting day of the monthly billing cycle. Use a value from 1 to 31. For example, if you set the value to 15, then the monthly billing cycle is from January 15 to February 15, and so on. If you do not provide a value, the monthly billing cycle corresponds to the calendar month. A brief description of the goods or services offered to the customer. Although it is optional, CyberSource recommends that you provide this field. The customer sees this on the page when approving the billing agreement, in the confirmation from PayPal when a billing agreement is created or updated, in the transaction detail history for each preapproved payment, and in the confirmation from PayPal when a preapproved payment is processed. Regular payment Billing agreement Billing agreement Billing agreement Required/ Optional Optional String (127) Optional String (2) Optional Integer (2) Optional Data Type & Length String (no length limit) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

49 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_mp_error paypal_mp_max paypal_mp_max_ edit Displays an error on the first page of the agreement flow (which the customer sees when they log in to the PayPal site to approve the agreement) indicating that the customer has a problem with their PayPal account. Include this field in the request if you have received an indication from PayPal that the customer needs to update their account to fulfill payment. Use one of the following values: 0 (default): No, do not show the error 1: Yes, show the error Maximum amount that you can withdraw from the customer's account for a preapproved payment. Whether the customer can edit the monthly maximum billing amount (paypal_mp_max). Use one of the following values: 0 (default): No, the customer cannot edit the value 1: Yes, the customer can edit the value Billing agreement Billing agreement Billing agreement Required/ Optional Data Type & Length Optional Integer (1) Required String (15) Optional Integer (1) paypal_mp_max_ min The lowest payment amount the customer is allowed to enter when editing the paypal_ mp_max value. Can be specified only if paypal_mp_max_edit=1. Billing agreement Optional String (15) paypal_mp_pay_ type The type of PayPal payment funding source you want the customer to use. Use one of the following values: Billing agreement Optional String (1) x (default): Any payment type is acceptable e: echeck i: Instant only paypal_mp_test_ amount A currency amount tested against PayPal's risk and fraud models but not charged to the customer. You receive the result of this test in the mp_test_result HTML variable in the reply POST from PayPal. See "Reply Variables for Creating a Billing Agreement," page 141. Billing agreement Optional String (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

50 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_quantity paypal_return paypal_rm This becomes the value for the quantity variable in the button. This is the quantity of items to be purchased. If omitted, the value defaults to 1 and does not show in the payment flow. Make sure to include this if you are providing the paypal_shipping2 field. Note Although CyberSource has a similar API field (item_#_quantity), the quantity variable in the button is NOT populated based on CyberSource s item_#_quantity field. After a customer approves a regular payment or a billing agreement at PayPal s site, they are returned to a URL at your Web site, for example: success.example.com CyberSource suggests that you set the default URL for regular payments and you use the API field override for billing agreements. Most likely you will have a different return URL for billing agreements. Note This value overrides the value you may have configured to use with PayPal s Auto Return. See "Enabling Auto Return," page 32. Method of the FORM submission by which PayPal returns data to your Web site. Use one of the following values: 0 (default): POST Regular payment Regular payment Billing agreement Billing agreement Required/ Optional See description Required Data Type & Length Integer (no limit) String (255) Optional Integer (1) 1: GET (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

51 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_shipping paypal_shipping2 Do NOT use this field if you are using purchasetotals_freightamount or if you have an item with item_#_ productcode=shipping_only or shipping_and_handling. CyberSource populates the shipping variable in the button based on the values for these fields. If you are not using purchasetotals_ freightamount or an item for shipping and handling, paypal_shipping becomes the value for the shipping variable in the button. This is a flat shipping charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity).the value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 39 for more details. This becomes the value for the shipping2 variable in the button. This is the cost of shipping each additional item beyond the first item. PayPal multiplies this value by the number of items in the order minus one (paypal_quantity -1) and then adds it to the values for the shipping variable and the handling variable in the button to give the total shipping and handling charge they display to the customer. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 39 for more details. Regular payment Regular payment Required/ Optional Data Type & Length Optional String (15) Optional String (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

52 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button paypal_tax paypal_undefined_ quantity paypalbuttoncreate Service_buttonType paypalbuttoncreate Service_run Do NOT use this field if you are using the purchasetotals_taxamount or item_#_ taxamount field. CyberSource populates the tax variable in the button based on your values for these fields. If you are not using the purchasetotals_ taxamount or item_#_taxamount field, paypal_tax becomes the value for the tax variable in the button. This is a flat tax for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 40 for more details. If set to 2, the customer will be able to edit the quantity at PayPal s site. They will see a quantity field that they must complete. If omitted or set to 0, the customer will not be able to edit the quantity, and a default quantity of 1 will be used. Type of button to create. Use one of the following values: buy: Regular payment button (PayPal s Buy Now button) preapproved_billing_ agreement: Billing agreement button shopping_cart: PayPal s Shopping Cart button Note If you are creating a button for a regular payment, CyberSource prefers that you use the buy button. Instructions for creating a shopping_cart button are included in Chapter 5, "Creating a Shopping Cart Button," on page 108. Set this field to true to request paypalbuttoncreateservice. Regular payment Regular payment Required/ Optional Data Type & Length Optional String (15) Optional Integer (1) All Required String (30) Both Required String (5) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

53 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button purchasetotals_ currency purchasetotals_ freightamount purchasetotals_ grandtotalamount purchasetotals_ taxamount This becomes the value for the currency_ code variable in the button. This is the currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. This becomes the value for the shipping variable in the button. This is the total freight amount for the order. If you include this field, purchasetotals_grandtotalamount is required. This value overrides any profile-based shipping charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 39 for more details. This becomes the value for the amount variable in the button. This is the grand total for the order. You must include either this field or item_#_unitprice in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. This becomes the value for the tax variable in the button.this is the total tax for the order. If you include this field, purchasetotals_ grandtotalamount is required. This value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 40 for more details. Regular payment Regular payment Regular payment Regular payment shipto_city City to which to ship the product. Regular payment shipto_country Country to which to ship the product. Use the two-character ISO codes. See the Support Center for a list of codes. Regular payment shipto_firstname First name of person receiving the product. Regular payment shipto_lastname Last name of person receiving the product. Regular payment Required/ Optional Required String (5) Optional String (15) See description Data Type & Length String (15) Optional String (15) Optional (1, 2) String (50) Optional (2) String (2) Optional (2) String (60) Optional (2) String (60) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

54 Chapter 3 Requesting Services with the Simple Order API Table 4 Button Create Request Fields (Continued) Request Field Description Use With Button shipto_postalcode shipto_ shippingmethod shipto_state shipto_street1 shipto_street2 Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the shipping country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the shipping country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 Shipping method for the product. For example, FEDEX. State or province to which to ship the product. Use the two-character codes. See the Support Center for a list of valid codes. First line of the address to which to ship the product. Second line of the address to which to ship the product. Regular payment Regular payment Regular payment Regular payment Regular payment Required/ Optional Data Type & Length Optional (2, 3) String (10) Optional String (10) Optional (2, 3) String (2) Optional (1, 2) String (60) Optional (2) String (60) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 39. (3) Required if shipto_country is US or CA. PayPal Services Implementation Guide September

55 Chapter 3 Requesting Services with the Simple Order API Reply Fields The following table describes the reply fields for creating a button. The fields you receive are the same for either type of button. Table 5 Reply Fields for Button Create Reply Field Description Data Type & Length decision invalidfield_0...n merchantreferencecode missingfield_0...n paypalbuttoncreatereply_ buttontype paypalbuttoncreatereply_ encryptedformdata paypalbuttoncreatereply_ reasoncode paypalbuttoncreatereply_ reconciliationid paypalbuttoncreatereply_ requestdatetime Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT ERROR REJECT Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Type of button created. This field will contain one of the following values: buy: Regular Buy Now payment button preapproved_billing_agreement: Billing agreement button shopping_cart: Shopping Cart button. See Chapter 5, "Creating a Shopping Cart Button," on page 108. Encrypted version of the button. A numeric value corresponding to the result of the button creation request. See "Reason Codes," page 70 for a list of possible values. Reference number for the transaction that you use to reconcile your transactions. Time of the button creation request. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. String (6) String (100) String (50) String (100) String (30) String (no length limit) Integer (5) String (60) String (20) PayPal Services Implementation Guide September

56 Chapter 3 Requesting Services with the Simple Order API Table 5 Reply Fields for Button Create (Continued) Reply Field Description Data Type & Length paypalbuttoncreatereply_ unencryptedformdata reasoncode Unencrypted version of the button. Numeric value corresponding to the result of the overall request. See "Reason Codes," page 70 for a list of possible values. String (no length limit) Integer (5) requestid Unique identifier for the request. String (26) requesttoken Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. String (256) Processing a Preapproved Payment After the customer has accepted the billing agreement, you may process preapproved payments according to the agreement. Use paypalpreapprovedpaymentservice to process each payment. In the paypalpreapprovedpaymentservice_mpid field you must include the customer's billing agreement identifier that you received when the customer accepted the billing agreement. See the description of mp_id in "Reply Variables for Creating a Billing Agreement," page 141. To request the service, set paypalpreapprovedpaymentservice_run=true. See Appendix A, "Examples for the Simple Order API," on page 110 for example requests and replies. The only other ICS service that you may call in conjunction with paypalpreapprovedpaymentservice is taxservice. See the Tax Calculation Implementation Guide. PayPal Services Implementation Guide September

57 Chapter 3 Requesting Services with the Simple Order API Request Fields The following table lists the request fields for processing a preapproved payment. Table 6 Preapproved Payment Request Fields Request Field Description Required / Optional Data Type & Length billto_city City of the billing address. Required String (50) billto_country Country of the billing address. Use the two-character ISO codes. See the Support Center for a list of codes. Required String (2) billto_ Customer s address, including the full domain Optional String name (for example, [email protected]). (255) billto_firstname Customer s first name. Required String (60) billto_lastname Customer s last name. Required String (60) billto_postalcode billto_state item_#_productcode item_#_productname item_#_productsku Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes. Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_quantity, item_#_productname, and item_#_productsku fields are required. Product s name. Required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Product s identifier code. Required if item_#_ productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Required if country is U.S. or Canada Required if country is U.S. or Canada String (10) String (2) Optional String (30) See description See description String (30) String (30) PayPal Services Implementation Guide September

58 Chapter 3 Requesting Services with the Simple Order API Table 6 Preapproved Payment Request Fields (Continued) Request Field Description Required / Optional item_#_quantity item_#_taxamount item_#_unitprice linktorequest merchantid merchantreferencecode paypal_customer_ paypal_ _subject Quantity of the product being purchased. The default value is 1. Required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Total tax to apply to the product. This value cannot be negative. The item_#_taxamount field is additive. For example, if you send one item with unitprice of $10.00 and taxamount of $0.80, and you send another item with unitprice of $20.00 and taxamount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included. The item_#_taxamount and the item_#_unitprice must be in the same currency. Per-item price of the product. You must include either this field or purchasetotals_grandtotalamount in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the Simple Order API. Your CyberSource merchant ID. Use the same merchantid for evaluation, testing, and production. Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced. Customer s address, including the full domain name (for example, [email protected]). Subject line of the confirmation that will be sent to the customer. See description Integer (10) Optional String (15) See description String (15) Optional String (26) Required String (30) Required String (50) Optional Optional Data Type & Length String (255) String (no length limit) paypal_item_name Name of the purchased item. Optional String (no length limit) PayPal Services Implementation Guide September

59 Chapter 3 Requesting Services with the Simple Order API Table 6 Preapproved Payment Request Fields (Continued) Request Field Description Required / Optional paypal_item_number Reference number of the purchased item. Optional String (no length limit) paypal_memo paypal_payment_type paypalpreapproved PaymentService_mpID paypalpreapproved PaymentService_run purchasetotals_currency purchasetotals_ grandtotalamount Text entered by the customer in the Note field during enrollment. The type of PayPal payment funding source to use. Use one of the following values: Any (default): Any payment type is acceptable EcheckOnly: echeck InstantOnly: Instant only Make sure to provide the value exactly as shown above. Optional String (no length limit) Optional String (11) Billing agreement identifier (the mp_id). Required String (19) Set to true to request paypalpreapprovedpaymentservice. Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. Grand total for the order. You must include either this field or item_#_unitprice in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. Required String (5) Required String (5) See description Data Type & Length String (15) PayPal Services Implementation Guide September

60 Chapter 3 Requesting Services with the Simple Order API Reply Fields The following table lists the reply fields for processing a preapproved payment. Table 7 Preapproved Payment Reply Fields Reply Field Description Data Type & Length decision Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT ERROR REJECT String (6) invalidfield_0...n merchantreferencecode missingfield_0...n paypalpreapproved PaymentReply_desc paypalpreapproved PaymentReply_exchangeRate paypalpreapproved PaymentReply_feeAmount paypalpreapproved PaymentReply_mpMax paypalpreapproved PaymentReply_mpStatus Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Value of the paypal_mp_desc field you provided when creating the billing agreement button. Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer's nonprimary currency. If the customer chooses to pay in a currency other than the non-primary currency, the conversion occurs in the customer's account. String (100) String (50) String (100) String (no length limit) String (15) PayPal fee amount charged for the transaction. String (15) Monthly maximum payment amount. String (15) Current status of the billing agreement. This field will contain one of the following values: Active Canceled String (9) PayPal Services Implementation Guide September

61 Chapter 3 Requesting Services with the Simple Order API Table 7 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypalpreapproved PaymentReply_payer paypalpreapproved PaymentReply_payerBusiness paypalpreapproved PaymentReply_payerCountry paypalpreapproved PaymentReply_payerID paypalpreapproved PaymentReply_payerName paypalpreapproved PaymentReply_payerStatus paypalpreapproved PaymentReply_paymentDate paypalpreapproved PaymentReply_ paymentgrossamount paypalpreapproved PaymentReply_paymentStatus paypalpreapproved PaymentReply_paymentType Customer's PayPal account identifier (customer's address). Customer's business name if the customer has a PayPal Business or Premier account. Customer's country of residence. PayPal-generated unique customer ID. Customer's name. Status of the customer's address. This field will contain one of the following values: verified: Customer s PayPal account is Verified unverified: Customer s PayPal account is Unverified PayPal's timestamp for the payment. Example: 18:30:30 Jan 1, 2000 PST. The final amount charged including any shipping or taxes from your PayPal profile. Status of the preapproved payment. This field will contain one of the following values: Completed Pending (see reasons in paypalpreapprovedpaymentreply_pendingreason below) Failed Retry Indicates whether the payment is instant or delayed. This field will contain one of the following values: echeck instant String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (10) String (20) String (15) String (9) String (7) PayPal Services Implementation Guide September

62 Chapter 3 Requesting Services with the Simple Order API Table 7 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypalpreapproved PaymentReply_pendingReason paypalpreapproved PaymentReply_reasonCode paypalpreapproved PaymentReply_reconciliationID paypalpreapproved PaymentReply_requestDateTime paypalpreapproved PaymentReply_settleAmount paypalpreapproved PaymentReply_taxAmount Reason if paypalpreapprovedpaymentreply_ paymentstatus=pending. This field will contain one of these values: address: Customer did not include a confirmed shipping address, and you have your Payment Receiving Preferences set to manually accept or deny each of these payments. echeck: Electronic check has not cleared yet. intl: You hold a non-u.s. account and do not have a withdrawal method. You must manually accept or deny this payment from your PayPal 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 the payment. You must manually accept or deny the payment. other: Payment is pending for a reason other than the other reasons listed here. Contact PayPal Customer Service. unilateral: The payment was made to an address that is not yet registered or confirmed. upgrade: Payment was made via credit card and you must upgrade your account to Business or Premier status to receive the funds. You could also get this status because you have reached the monthly limit for transactions on your account. verify: You are not yet verified. You must verify your account before you can accept the payment. A numeric value corresponding to the result of the billing agreement update request. See "Reason Codes," page 70 for a list of possible values. Reference number for the transaction that you use to reconcile your transactions. Time of the preapproved payment request. The format is YYYY-MM-DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Amount deposited in your PayPal account after a currency conversion. String (14) Integer (5) String (60) String (20) String (15) Tax charged on the transaction. String (15) PayPal Services Implementation Guide September

63 Chapter 3 Requesting Services with the Simple Order API Table 7 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypalpreapproved PaymentReply_transactionID paypalpreapproved PaymentReply_transactionType reasoncode requesttoken PayPal's unique transaction ID for the payment. Type of PayPal payment. This field will contain the value mercht-pmt. Numeric value corresponding to the result of the overall request. See "Reason Codes," page 70 for a list of possible values. Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. String (no length limit) Integer (5) String (256) Canceling or Updating a Billing Agreement You can cancel a billing agreement or update a billing agreement with a new description of the goods and services. To do either of these, use paypalpreapprovedupdateservice. You may not update the maximum amount for a billing agreement. To request the service, send a request with paypalpreapprovedupdateservice_ run=true. Do not include any other ICS services in the request. See Appendix A, "Examples for the Simple Order API," on page 110 for example requests and replies. You can view the details of a billing agreement in the Business Center. See "Billing Agreements," page 12 for more information. PayPal Services Implementation Guide September

64 Chapter 3 Requesting Services with the Simple Order API Request Fields The following table lists the request fields for updating a billing agreement. Table 8 Billing Agreement Update Request Fields Request Field Description Required / Optional merchantid merchantreferencecode paypalpreapprovedupdateservice_run paypalpreapprovedupdateservice_mpid paypal_mp_desc paypal_mp_status Your CyberSource merchant ID. Use the same merchantid for evaluation, testing, and production. Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced. Set this field to true to request paypalpreapprovedupdate Service. Billing agreement identifier (the mp_ id) that you received from PayPal. Description of the goods or services associated with the billing agreement. Set this field to Canceled to cancel the billing agreement. The value is case sensitive, so make sure to set it exactly as shown here. Data Type & Length Required String (30) Required String (50) Required String (5) Required String (19) Optional String (no length limit) Optional String (8) PayPal Services Implementation Guide September

65 Chapter 3 Requesting Services with the Simple Order API Reply Fields The following table lists the reply fields for updating a billing agreement. Table 9 Billing Agreement Update Reply Fields Reply Field Description Data Type & Length decision Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT ERROR REJECT String (6) invalidfield_0...n merchantreferencecode missingfield_0...n paypalpreapproved UpdateReply_desc paypalpreapproved UpdateReply_mpMax paypalpreapproved UpdateReply_mpStatus Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. Value of the paypal_mp_desc field you provided when creating the billing agreement button. String (100) String (50) String (100) String (no length limit) Monthly maximum payment amount. String (15) Current status of the billing agreement. This field will contain one of the following values: Active Canceled String (9) paypalpreapproved UpdateReply_payer paypalpreapproved UpdateReply_payerBusiness paypalpreapproved UpdateReply_payerCountry paypalpreapproved UpdateReply_payerID Customer's PayPal account identifier (customer's address). Customer's business name if the customer has a PayPal Business or Premier account. Customer's country of residence. PayPal-generated unique customer ID. String (no length limit) String (no length limit) String (no length limit) String (no length limit) PayPal Services Implementation Guide September

66 Chapter 3 Requesting Services with the Simple Order API Table 9 Billing Agreement Update Reply Fields (Continued) Reply Field Description Data Type & Length paypalpreapproved UpdateReply_payerName paypalpreapproved UpdateReply_payerStatus Customer's name. Status of the customer's address. This field will contain one of the following values: verified: Customer s PayPal account is Verified unverified: Customer s PayPal account is Unverified String (no length limit) String (10) paypalpreapproved UpdateReply_reasonCode paypalpreapproved UpdateReply_reconciliationID paypalpreapproved UpdateReply_requestDateTime reasoncode A numeric value corresponding to the result of the billing agreement update request. See "Reason Codes," page 70 for a list of possible values. Reference number for the transaction that you use to reconcile your transactions. Time of the billing agreement update request. The format is YYYY-MM-DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Numeric value corresponding to the result of the overall request. See "Reason Codes," page 70 for a list of possible values. Integer (5) String (60) String (20) Integer (5) requestid Unique identifier for the request. String (26) requesttoken Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. String (256) PayPal Services Implementation Guide September

67 Chapter 3 Requesting Services with the Simple Order API Processing a Credit You can perform a credit for a regular payment or a preapproved payment by using paypalcreditservice. For general information about refunding PayPal payments, see "PayPal Credits," page 13. Important You must perform the credit within 60 days of the payment request. At this time, you can perform only one credit for an order, for either a partial amount or the full amount of the payment. To request the service, send a request with paypalcreditservice_run=true. A PayPal credit is a follow-on service. It uses the requestid returned from a previous paypalbuttoncreateservice or paypalpreapprovedpaymentservice request to link the credit to the payment. Send the request ID value in the paypalcreditservice_ paypalpaymentrequestid field. CyberSource uses these values to look up the customer s billing and account information from the original payment, so you do not have to supply those fields in the paypalcreditservice request. See Appendix A, "Examples for the Simple Order API," on page 110 for example requests and replies. When requesting the service, do not include any other ICS services in the request. Request Fields The following table lists the request fields for processing a credit. Table 10 PayPal Credit Request Fields Request Field Description Required / Optional item_#_productcode Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. Data Type & Length Optional String (30) item_#_productname Product s name. Optional String (30) item_#_productsku Product s identifier code. Optional String (30) item_#_quantity Quantity of the product being returned. Optional Integer (10) item_#_taxamount Total tax to apply to the product. Optional String (15) item_#_unitprice Amount of the credit. At this time, you can perform only one credit for an order, for either a partial amount or the full amount of the payment. You must include either this field or purchasetotals_ grandtotalamount in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. See description String (15) PayPal Services Implementation Guide September

68 Chapter 3 Requesting Services with the Simple Order API Table 10 PayPal Credit Request Fields (Continued) Request Field Description Required / Optional merchantid merchantreferencecode orderrequesttoken Your CyberSource merchant ID. Use the same merchantid for evaluation, testing, and production. Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced. The request token value returned from a previous request. This value links the previous request to the current follow-on request. This field is an encoded string that does not contain any confidential information, such as account numbers or card verification numbers. The string can contain a maximum of 256 characters. Required String (30) Required String (50) Required Data Type & Length String (256) paypalcreditservice_ paypalpaymentrequest ID Request ID from the payment reply. Required String (26) paypalcreditservice_ paypalpaymentrequest Token The requesttoken value returned from a previous request for paypalbuttoncreateservice or paypalpreapprovedpaymentservice. Optional String (256) The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters. paypalcreditservice_run Set to true to request paypalcreditservice. Required String (5) purchasetotals_currency purchasetotals_ grandtotalamount Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. Amount of the credit. At this time, you can perform only one credit for an order, for either a partial amount or the full amount of the payment. You must include either this field or item_#_unitprice in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. Required String (5) See description String (15) PayPal Services Implementation Guide September

69 Chapter 3 Requesting Services with the Simple Order API Reply Fields The following table lists the reply fields for processing a credit. Table 11 PayPal Credit Reply Fields Reply Field Description Data Type & Length decision Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT ERROR REJECT String (6) invalidfield_0...n merchantreferencecode missingfield_0...n Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction.see the information about missing and invalid fields in Getting Started with CyberSource Advanced. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. String (100) String (50) String (100) paypalcreditreply_amount Amount of the credit. String (15) paypalcreditreply_ reasoncode paypalcreditreply_ reconciliationid paypalcreditreply_ requestdatetime A numeric value corresponding to the result of the PayPal credit request. See "Reason Codes," page 70 for a list of possible values. Reference number for the transaction that you use to reconcile your transactions. Time of the PayPal credit. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Integer (5) String (60) String (20) purchasetotals_currency Currency used for the order. String (5) reasoncode Numeric value corresponding to the result of the overall request. See "Reason Codes," page 70 for a list of possible values. Integer (5) requestid Unique identifier for the request. String (26) requesttoken Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. String (256) PayPal Services Implementation Guide September

70 Chapter 3 Requesting Services with the Simple Order API Reason Codes The following table lists the reason codes returned by the Simple Order API for the PayPal Services. See the information about handling replies in Getting Started with CyberSource Advanced for a discussion of replies, decisions, and reason codes. Important Because CyberSource may add reply fields and reason codes at any time, proceed as follows: You should parse the reply data according to the names of the fields instead of their order in the reply. For more information on parsing reply fields, see the documentation for your client. Your error handler should use the decision field to determine the result if it receives a reason code that it does not recognize. Table 12 Reason Code Reason Codes Description 100 Successful transaction. 101 The request is missing one or more required fields. Possible action: See the reply fields missingfield_0...n for which fields are missing. Resend the request with the complete information. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. 102 One or more fields in the request contains invalid data. Possible action: See the reply fields invalidfield_0...n for which fields are invalid. Resend the request with the correct information. See the information about missing and invalid fields in Getting Started with CyberSource Advanced. 150 Error: General system failure. See the documentation for your CyberSource client for information about how to handle retries in the case of system errors. 151 Error: The request was received but there was a server timeout. This error does not include timeouts between the client and the server. Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. See the documentation for your CyberSource client for information about how to handle retries in the case of system errors. 152 Error: The request was received, but a service did not finish running in time. Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. See the documentation for your CyberSource client for information about how to handle retries in the case of system errors. PayPal Services Implementation Guide September

71 Chapter 3 Requesting Services with the Simple Order API Table 12 Reason Code Reason Codes (Continued) Description 223 A request was made to credit an order for which there is no corresponding, unused payment record. Occurs if there was not a previously successful paypalbuttoncreateservice or paypalpreapprovedpaymentservice request, or if the previously successful payment has already been used by another paypalcreditservice request. Possible action: Verify that have not already credited this payment, or verify that you are crediting the correct payment. 233 General decline by the processor. Possible action: Request a different form of payment. 234 There is a problem with your CyberSource merchant configuration. Possible action: Do not resend the request. Contact Customer Support to correct the configuration problem. 236 Processor failure. Possible action: Wait a few minutes and resend the request. 239 The requested transaction amount must match the previous transaction amount. Possible action: Correct the amount and resend the request. 241 The request ID is invalid. Possible action: Verify you are using the correct request ID. 250 Error: The request was received, but there was a timeout at the payment processor. Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. Testing You can use CyberSource s regular testing environment for sending test transactions. If using the Simple Order API, make sure your CyberSource client is configured to send transactions to the test server. See the documentation for your client for information about how to do this. The buttons generated by CyberSource s test system submit the form to PayPal s Sandbox test environment ( You need to set up your Sandbox account as soon as you begin creating your implementation. See PayPal s Sandbox User Guide for instructions. Always log in to the Sandbox before clicking any of your test buttons. Then when you click a test button, you will automatically go to the Sandbox site, which mimics the live PayPal site that the customer logs in to. PayPal Services Implementation Guide September

72 Requesting Services with the SCMP API CHAPTER 4 Creating Buttons The ics_paypal_button_create service lets you create these kinds of buttons: One for processing a regular payment with an aggregate amount for the order (PayPal s Buy Now button) Note PayPal also has a Shopping Cart button that uses individual item information and amounts instead of an aggregate order total. This chapter discusses how to create PayPal s Buy Now button. For information about requesting a Shopping Cart button, see Chapter 5, "Creating a Shopping Cart Button," on page 108. One for creating the billing agreement for preapproved payments For information about regular and preapproved payments, see "PayPal Payments," page 8. Requesting the Service To request the service, send a request with ics_applications=ics_paypal_button_ create. Use the button_type field to indicate which type of button you want. See Appendix B, "Examples for the SCMP API," on page 128 for example requests. When creating a regular payment button, the only other ICS service you can include in the request is ics_tax. For more information, see the Tax Calculation Implementation Guide. When creating a billing agreement button, do not include any other ICS services in the request. PayPal s HTML Variables for a Regular Payment Button The regular payment button (PayPal s Buy Now button) that CyberSource creates includes a list of HTML variables that give transaction information to PayPal and that control the display of the PayPal site when the customer goes there to approve the payment. CyberSource adds paypal_ before the name of each variable to create the corresponding CyberSource API field that you use when creating the button. For example, PayPal Services Implementation Guide September

73 Chapter 4 Requesting Services with the SCMP API PayPal has a variable called return. The field you include in your request to CyberSource is paypal_return. See the paypal_... fields in Table 15, page 78. Not all of the available PayPal HTML variables are listed in Table 15; only the basic ones you need to process a payment are included. For the entire list of HTML variables available for use with a Buy Now button, see PayPal s Merchant User Manual and Integration Guide. If PayPal s guide lists any variables that you want to use that are not already listed in Table 15, simply add the corresponding paypal_<variable_name> field to your ics_paypal_button_create request to include that variable in the button. This also allows you to easily use any new Buy Now button variables that PayPal might create in the future. CyberSource does not validate the content of the HTML variable API fields that you send. Important For some of the available HTML variables, CyberSource automatically assigns values and does not need your input. Specifically, CyberSource sets the values for cmd, business, custom, invoice, and notify_url and does not provide corresponding API fields for you to use. If you send fields called paypal_cmd, paypal_business, paypal_custom, paypal_invoice, or paypal_notify_url in your request, the request will be rejected. Some of CyberSource s regular API fields for specifying amounts and offer-level information are similar to or duplicate the function of some of PayPal s HTML fields. For example, PayPal has an HTML variable called amount. CyberSource has similar API fields called grand_total_amount and the offer-level field amount (and one of these two are required in the ics_paypal_button_create request). CyberSource automatically populates the PayPal amount variable that is included in the button with a value based on the grand_total_amount or the offer-level amount values that you provide in your ics_ paypal_button_create request. However, you could theoretically include paypal_amount in your request in addition to a grand_total_amount or the offer-level amount values, because CyberSource allows you to pass most of the available PayPal variables generically as paypal_<variable name> through the CyberSource API. But you should not do this because CyberSource will then include two values for the amount variable in the button: one based on the grand_total_ amount or the offer-level amount values, and one based on the paypal_amount field you sent. This might lead to unpredictable amount values being displayed at PayPal s site when the customer goes there to approve the payment. If a particular PayPal HTML variable is being populated by CyberSource based on the value you provide for a similar CyberSource API field, the description for that PayPal variable in Table 15, page 78 will say so. For example, see the description for paypal_ amount in the table. PayPal Services Implementation Guide September

74 Chapter 4 Requesting Services with the SCMP API Sending the Shipping Address for a Regular Payment Button When creating a regular payment button, you should include the shipping address in the request even though it is optional. PayPal will check the shipping address you provide against the customer s list of confirmed addresses. If the address is one of the confirmed addresses, the transaction may be eligible for chargeback protection under PayPal s Seller Protection Policy. See PayPal s Security Center at for more information. If you do not send a shipping address in your request, CyberSource will not substitute the billing address for the shipping address when sending the information to PayPal. To determine if the shipping address was confirmed or unconfirmed, search for the transaction in the Business Center. The transaction details include whether the address was confirmed or unconfirmed. Specifying Shipping and Handling Charges for a Regular Payment Button CyberSource and PayPal both have methods for you to specify freight charges (shipping and handling charges). When creating a regular payment button for an order with freight charges, you need to choose which method you want to use to specify the freight amount. You might already be familiar with CyberSource s methods if you process other payment types with CyberSource. The following table describes your choices. CyberSource s methods override any PayPal profiled-based shipping and handling settings you have. Important You should choose one of these methods and not send CyberSource shipping and handling fields as well as PayPal HTML variables for shipping and handling. If you do, the customer may see unexpected amounts for the shipping and handling when they go to PayPal s site to approve the payment. PayPal Services Implementation Guide September

75 Chapter 4 Requesting Services with the SCMP API Table 13 Methods for Specifying Shipping and Handling Charges Method CyberSource: Using a total freight amount CyberSource: Using an offer for the freight amount PayPal: Using a profile-based freight amount PayPal: Overriding the profilebased freight amount Description If you are using CyberSource s grand_total_amount field to give a total amount for the order, then you must use the freight_amount field to give the total shipping and handling for the order. CyberSource will map this to the PayPal HTML variable shipping. This method overrides any profile-based amount you have set. See below. If you are using offer-level information instead of the grand_total_ amount field, you must create at least one separate item for the shipping and/or handling amounts. For more details, see the information about offers and grand totals in Getting Started with CyberSource Advanced. CyberSource will sum the amounts for offers where the product_code=shipping_only or shipping_and_handling and assign the value to the PayPal HTML variable shipping. CyberSource will sum the amounts for offers where the product_code= handling_only and assign the value to the PayPal HTML variable handling. This method overrides any profile-based amount you have set. See below. You can configure your PayPal profile to use flat shipping and handling amounts based on the overall order total. See PayPal s Merchant User Manual and Integration Guide for more information. You can configure your PayPal account so that you can override the flat profile-based shipping and handling amounts by using specific HTML variables when creating the button. PayPal s shipping, handling, and shipping2 HTML variables let you do this. See the descriptions of the corresponding CyberSource API fields paypal_shipping, paypal_handling, and paypal_shipping2 in Table 15, page 78. Specifying Tax for a Regular Payment Button CyberSource and PayPal both have methods for you to specify the tax for an order. When creating a regular payment button for an order with tax, you need to choose which method you want to use to specify the tax amount. You might already be familiar with CyberSource s methods if you process other payment types with CyberSource. The following table describes your choices. CyberSource s methods override any PayPal profiled-based tax settings you have. Important You should choose one of these methods and not send CyberSource tax fields as well as PayPal HTML variables for tax. If you do, the customer may see unexpected amounts for the tax when they go to PayPal s site to approve the payment. PayPal Services Implementation Guide September

76 Chapter 4 Requesting Services with the SCMP API Table 14 Methods for Specifying an Order s Tax Method CyberSource: Using a total tax amount CyberSource: Using an item-level tax amount PayPal: Using a profile-based tax amount PayPal: Overriding the profilebased tax amount Description If you are using CyberSource s grand_total_amount field to give a total amount for the order, then you must use the total_tax_amount field to give the total tax for the order. This method overrides any profile-based amount you have set. See below. If you are using item-level information instead of the grand_total_ amount field, you must specify the total tax for each item in the offerlevel field tax_amount. For more details, see the information about offers and grand totals in Getting Started with CyberSource Advanced. This method overrides any profile-based amount you have set. See below. You can configure your PayPal profile to use certain tax amounts based on the customer s country and state. See PayPal s Merchant User Manual and Integration Guide for information. You can configure your PayPal account so that you can override the profile-based tax amount by using a the tax HTML variable when creating the button. See the description of the corresponding CyberSource API field paypal_tax in Table 15, page 78. Interpreting CyberSource s Reply CyberSource returns to you an encrypted version and an unencrypted version of the button in the paypal_button_create_encrypted_form_data and paypal_button_ create_unencrypted_form_data fields, respectively. Use the encrypted version when in production and the unencrypted version when troubleshooting or testing your system. See Appendix B, "Examples for the SCMP API," on page 128 for example replies. You insert the button into your HTML page like this: <html> <body> <!-- Insert your page header --> Click PayPal Checkout to proceed with your PayPal payment. This will take you to the PayPal login page. <!-- Replace the "%s" below with the button, which is a self-contained form that CyberSource returns to you. --> %s </body> </html> PayPal Services Implementation Guide September

77 Chapter 4 Requesting Services with the SCMP API The encrypted version of the button looks similar to this: <form action=" method="post"><input type="image" src=" border="0" name="submit"><input type="hidden" name="cmd" value="_s-xclick"><input type="hidden" name="encrypted" value="-----begin PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhM CVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQ EBAQUABIGAg0SFsADkAz5l03qK8we8z3zt86F9IZB8q8J+oCSjmBWgrZdh+VKHgPL2SKuRG rifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/r7hqzd/e1isljufz9/ikqo2hk/ wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/xmlpuoljanqnx2mvmi85hhpmacam-----end PKCS7-----"</form> Note The encrypted information in the above example has been shortened for illustration. The actual length of the information is about characters. The unencrypted version of the button looks similar to this: <form action=" method="post"><input type="image" src=" border="0" name="submit"><input type="hidden" name="cmd" value="_s-xclick"><input type="hidden" name="business" value="[email protected]"><input type="hidden" name="first_name" value="larry"><input type="hidden" name="last_name" value="smith"><input type="hidden" name="address1" value="37 Main St."><input type="hidden" name="address2" value="suite 2"><input type="hidden" name="city" value="bloomington"><input type="hidden" name="state" value="in"><input type="hidden" name="zip" value="47404"><input type="hidden" name="amount" value="0.00"><input type="hidden" name="tax" value="0"><input type="hidden" name="handling" value="0.00"><input type="hidden" name="shipping" value="0.00"><input type="hidden" name="item_number" value="123454"><input type="hidden" name="cancel_return" value=" type="hidden" name="undefined_quantity" value="1"><input type="hidden" name="quantity" value="5"><input type="hidden" name="return" value=" type="hidden" name="item_name" value="book"><input type="hidden" name="shipping2" value="0.00"><input type="hidden" name="currency_code" value="usd"><input type="hidden" name="bn" value="cybersource"><input type="hidden" name="notify_url" value=" type="hidden" name="invoice" value=" "><input type="hidden" name="custom" value=" , ,001"></form> Receiving PayPal s POST Response If you are using PayPal s Payment Data Transfer (PDT), you receive a POST from PayPal when the customer is redirected back to your site after approving a regular payment. See "Information from PayPal: Payment Data Transfer (PDT)," page 15. The POST contains a PayPal Services Implementation Guide September

78 Chapter 4 Requesting Services with the SCMP API variable called st that indicates whether you can fulfill the order. See "PDT Reply Variables," page 140 for a full list of information you receive. When a customer approves a billing agreement at PayPal s site, PayPal sends the customer back to your Web site while POSTing information about the billing agreement (note that this POST has nothing to do with whether you are using PDT). You must make sure to store the mp_id that you receive because that is the billing agreement identifier that you need to process preapproved payments for the customer later. For a complete list of the return variables you receive, see "Reply Variables for Creating a Billing Agreement," page 141. Request-Level Fields The following table lists the request-level fields for ics_paypal_button_create. The table indicates whether to use each field when creating a regular payment or billing agreement button. Table 15 Button Create Request-Level Fields Request-Level Field Description Type of Button Required/ Optional Data Type & Length bill_city City of the billing address. Both Required String (50) bill_country bill_state bill_zip Country of the billing address. Use the twocharacter ISO codes. See the Support Center for a list of codes. State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes. Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 Both Required String (2) Both Both Required if country is U.S. or Canada Required if country is U.S. or Canada String (2) String (10) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

79 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button button_type currency customer_ Type of button to create. Use one of the following values: buy: Regular payment button (PayPal s Buy Now button) preapproved_billing_ agreement: Billing agreement button shopping_cart: PayPal s Shopping Cart button Note CyberSource s preferred solution if you are creating a button for a regular payment is the buy button. Instructions for creating a shopping_cart button are included in Chapter 5, "Creating a Shopping Cart Button," on page 108. This becomes the value for the currency_ code variable in the button. This is the currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. Customer s address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]). All Required String (30) Regular payment Required String (5) Both Optional String (255) customer_firstname Customer s first name. Both Required String (60) customer_lastname Customer s last name. Both Required String (60) freight_amount This becomes the value for the shipping variable in the button. This is the total freight amount for the order. If you include this field, grand_total_amount is required. This value overrides any profile-based shipping charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details. Regular payment Required/ Optional Optional Data Type & Length Decimal (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

80 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button grand_total_amount This becomes the value for the amount variable in the button. This is the grand total for the order. You must include either this field or offer0 and the offer-level field amount. See the information about offers and grand totals in Getting Started with CyberSource Advanced. Regular payment See description Decimal (15) ics_applications ICS services to process for the request. Both Required String (255) link_to_request merchant_id merchant_ref_number offer0...n paypal_amount Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the SCMP API. Your CyberSource merchant ID. Use the same merchant_id for evaluation, testing, and production. Merchant-generated order reference or tracking number. CyberSource suggests that you use a unique value for each order or billing agreement. See the information about order tracking in Getting Started with CyberSource Advanced. Offers (line items of the order) for the request. You must include either offer0 and the offerlevel field amount, or the request-level field grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced. CyberSource suggests you do NOT use this PayPal HTML variable in your request for a regular payment button as you will already be specifying a grand_total_amount or offerlevel amount which will be used to populate PayPal s amount variable in the button. See "PayPal s HTML Variables for a Regular Payment Button," page 72 for more information. Regular payment Optional String (26) Both Required String (30) Both Required String (50) Regular payment Neither Required/ Optional See description See description Data Type & Length String (50) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. N/A PayPal Services Implementation Guide September

81 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_cancel_return paypal_customer_ paypal_handling paypal_item_name URL of the Web page to show the customer if the customer cancels the regular PayPal payment, for example: cancel.example.com. Customer s address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]). Do NOT use this field if you are using freight_amount or if you have an offer with product_code= handling_only. CyberSource populates the handling variable in the button based on your values for these fields. If you are not using freight_amount or an offer for handling, paypal_handling becomes the value for the handling variable in the button. This is a flat handling charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details. This becomes the value for the item_name variable in the button. This is the description of the item. If omitted, the customer will see a field that they can use to enter a description of the item. Note Although CyberSource has a similar API field (offer-level field product_name), the item_name variable will NOT be populated based on CyberSource s product_ name field. You may include both paypal_ item_name and product_name in the request. Regular payment Optional String (255) Both Optional String (255) Regular payment Regular payment Required/ Optional Optional Optional Data Type & Length Decimal (15) String (127) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

82 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_item_number paypal_lc paypal_mp_cycle_ start paypal_mp_desc This becomes the value for the item_ number variable in the button. It is not displayed to the customer, but it is passed back to you upon completion of the payment. If omitted, it is not passed back to you. Note Although CyberSource has a similar API field (the offer-level field merchant_ product_sku), the item_number variable in the button will NOT be populated based on CyberSource s merchant_product_sku field. You may include both paypal_item_ number and merchant_product_sku in the request. Locale (language) for the billing agreement pages. Use the two-character ISO country codes. Defines the starting day of the monthly billing cycle. Use a value from 1 to 31. For example, if you set the value to 15, then the monthly billing cycle is from January 15 to February 15, and so on. If you do not provide a value, the monthly billing cycle corresponds to the calendar month. A brief description of the goods or services offered to the customer. Although it is optional, CyberSource recommends that you provide this field. The customer sees this on the page when approving the billing agreement, in the confirmation from PayPal when a billing agreement is created or updated, in the transaction detail history for each preapproved payment, and in the confirmation from PayPal when a preapproved payment is processed. Regular payment Billing agreement Billing agreement Billing agreement Required/ Optional Optional String (127) Optional String (2) Optional Integer (2) Optional Data Type & Length String (no length limit) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

83 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_mp_error paypal_mp_max paypal_mp_max_edit Displays an error on the first page of the agreement flow (which the customer sees when they log in to the PayPal site to approve the agreement) indicating that the customer has a problem with their PayPal account. Include this field in the request if you have received an indication from PayPal that the customer needs to update their account to fulfill payment. Use one of the following values: 0 (default): No, do not show the error 1: Yes, show the error Maximum amount that you can withdraw from the customer's account for a preapproved payment. Whether the customer can edit the monthly maximum billing amount (paypal_mp_max). Use one of the following values: 0 (default): No, the customer cannot edit the value 1: Yes, the customer can edit the value Billing agreement Billing agreement Billing agreement Required/ Optional Optional Integer (1) Required Optional Data Type & Length Decimal (15) Decimal (1) paypal_mp_max_min paypal_mp_pay_type paypal_mp_test_ amount The lowest payment amount the customer is allowed to enter when editing the paypal_ mp_max value. Can be specified only if paypal_mp_max_edit=1. The type of PayPal payment funding source you want the customer to use. Use one of the following values: x (default): Any payment type is acceptable e: echeck i: Instant only A currency amount tested against PayPal's risk and fraud models but not charged to the customer. You receive the result of this test in the mp_test_result HTML variable in the reply POST from PayPal. See "Reply Variables for Creating a Billing Agreement," page 141. Billing agreement Billing agreement Billing agreement Optional Decimal (15) Optional String (1) Optional Decimal (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

84 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_quantity paypal_return paypal_rm This becomes the value for the quantity variable in the button. This is the quantity of items to be purchased If omitted, the value defaults to 1 and does not show in the payment flow. Make sure to include this if you are providing the paypal_shipping2 field. Note Although CyberSource has a similar API field (the offer-level field quantity), the quantity variable in the button will NOT be populated based on CyberSource s quantity field. Any value you pass here will be displayed as the quantity value in the button. After a customer approves a regular payment or a billing agreement at PayPal s site, they are returned to a URL at your Web site, such as: CyberSource suggests that you set the default URL for regular payments, and you use the API field override for billing agreements. Most likely you will have a different return URL for billing agreements. Note This value overrides the value you have configured to use with PayPal s Auto Return. See "Enabling Auto Return," page 32. Method of the FORM submission by which PayPal returns data to your Web site. Use one of the following values: 0 (default): POST 1: GET Regular payment See description Nonnegative integer (no limit) Both Optional String (255) Billing agreement Required/ Optional Optional Data Type & Length Nonnegative integer (1) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

85 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_shipping paypal_shipping2 Do NOT use this field if you are using freight_amount or if you have an offer with product_code=shipping_only or shipping_and_handling. CyberSource populates the shipping variable in the button based on your values for these fields. If you are not using freight_amount or an offer for shipping and handling, paypal_ shipping becomes the value for the shipping variable in the button. This is a flat shipping charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details. This becomes the value for the shipping2 variable in the button. This is the cost of shipping each additional item beyond the first item. PayPal multiplies this value by the number of items in the order minus one (paypal_quantity -1) and then adds it to the values for the shipping variable and the handling variable in the button to give the total shipping and handling charge they display to the customer. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details. Regular payment Regular payment Required/ Optional Optional Optional Data Type & Length Decimal (15) Decimal (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

86 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button paypal_tax paypal_undefined_ quantity ship_to_address1 ship_to_address2 Do NOT use this field if you are using the total_tax_amount field or the offer-level tax_ amount field. CyberSource populates the tax variable in the button based on your values for these fields. If you are not using total_tax_amount or an offer-level tax_amount field, paypal_tax becomes the value for the tax variable in the button. This is a flat tax charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 75 for more details. If set to 2, the customer will be able to edit the quantity at PayPal s site. They will see a quantity field that they must complete. If omitted or set to 0, the customer will not be able to edit the quantity, and a default quantity of 1 will be used. First line of the address to which to ship the product. Second line of the address to which to ship the product. Regular payment Regular payment Regular payment Regular payment ship_to_city City to which to ship the product. Regular payment ship_to_country Country to which to ship the product. Use the two-character ISO codes. See the Support Center for a list of codes. Regular payment ship_to_firstname First name of person receiving the product. Regular payment ship_to_lastname Last name of person receiving the product. Regular payment ship_to_state State or province to which to ship the product. Use the two-character codes. See the Support Center for a list of valid codes. Regular payment Required/ Optional Optional Optional Data Type & Length Decimal (15) Nonnegative integer (1) Optional (1, 2) String (60) Optional (2) String (60) Optional (1, 2) String (50) Optional (2) String (2) Optional (2) String (60) Optional (2) String (60) Optional (2, 3) String (2) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

87 Chapter 4 Requesting Services with the SCMP API Table 15 Button Create Request-Level Fields (Continued) Request-Level Field Description Type of Button ship_to_zip shipping_method timeout total_tax_amount Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the shipping country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the shipping country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 Shipping method for the product. For example, FEDEX. Number of seconds the system waits before the transaction times out. The default is 110 seconds. This becomes the value for the tax variable in the button.this is the total tax for the order. If you include this field, grand_total_amount is required. This value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 75 for more details. Regular payment Regular payment Optional (2, 3) String (10) Optional String (10) Both Optional Positive integer (3) Regular payment Required/ Optional Optional Data Type & Length Decimal (15) (1) Required if any shipping information is included. (2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74. (3) Required if ship_to_country is US or CA. PayPal Services Implementation Guide September

88 Chapter 4 Requesting Services with the SCMP API Offer-Level Fields The following table describes the offer-level fields for ics_paypal_button_create. Table 16 Button Create Offer-Level Fields Offer-Level Field Description Type of Button amount merchant_ product_sku product_code Per-item price of the product. You must include either this field or grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. This field is used to calculate the value that goes into the amount variable in the button. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Product s identifier code. This information is not displayed in the button but is displayed in the transaction details screen on the Business Center. Required if product_code is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is NOT used for the item_ number variable in the button; paypal_item_ number is used for that; see the field description in Table 15. You may include both merchant_product_sku and paypal_item_ number in the request. Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the quantity, product_name, and merchant_product_sku fields are required. Regular payment Regular payment Regular payment Required/ Optional See description See description Optional Data Type & Length Decimal (15) String (30) String (30) PayPal Services Implementation Guide September

89 Chapter 4 Requesting Services with the SCMP API Table 16 product_name quantity tax_amount Button Create Offer-Level Fields (Continued) Offer-Level Field Description Type of Button Product s name. This information is not displayed in the button but is displayed on the transaction details screen in the Business Center. Required if product_code is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is NOT used for the item_ name variable in the button; paypal_item_ name is used for that; see the field description in this table. You may include both product_ name and paypal_item_name in the request. Quantity of the product being purchased. The default value is 1. Required if product_code for the offer is NOT default, stored_value, or one of the values related to shipping and/or handling. Note This value is NOT used for the quantity variable in the button; paypal_ quantity is used for that; see the field description in Table 15. This field is used to calculate the value that goes into the amount variable in the button. You may include both quantity and paypal_quantity in the request. The sum of these values for all of the items becomes the value for the tax variable in the button.this is the total tax to apply to the product. The value is NOT multiplied by the offer-level quantity. This value overrides any profile-based tax you have set. See "Specifying Tax for a Regular Payment Button," page 75 for more details. The tax_amount field is additive. For example, if you send the following offer lines: offer0=amount:10.00^quantity:1^ tax_amount:0.80 offer1=amount:20.00^quantity:1^ tax_amount:1.60 the total amount will be for $32.40, not $30.00 with $2.40 of tax included. (continues below) The tax_amount and the amount must be in the same currency. The value cannot be negative. Regular payment Regular payment Regular payment Required/ Optional See description See description Optional Data Type & Length String (30) Nonnegative integer (10) Decimal (15) PayPal Services Implementation Guide September

90 Chapter 4 Requesting Services with the SCMP API Reply Fields The following table describes the reply fields for ics_paypal_button_create. The fields you receive are the same for either type of button. Table 17 Button Create Reply Fields Reply Field Description Data Type & Length client_lib_version ics_rcode ics_rflag ics_rmsg merchant_ref_number paypal_button_ create_button_type paypal_button_create_ encrypted_form_data paypal_button_ create_rcode paypal_button_ create_rflag paypal_button_ create_rmsg Information about the client library used to request the transaction. One-digit code that indicates whether the entire request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the entire request. See Table 18, page 91 for a list of possible values. Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Type of button created. This field will contain one of the following values: buy: Regular Buy Now payment button preapproved_billing_agreement: Billing agreement button shopping_cart: Shopping Cart button. See Chapter 5, "Creating a Shopping Cart Button," on page 108. Encrypted version of the button. One-digit code that indicates whether the ics_paypal_button_ create request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the ics_paypal_button_ create request. See Table 18, page 91 for a list of possible values. Message that explains the reply flag paypal_button_create_ rflag. Do not display this message to the customer, and do not use this field to write an error handler. String (50) Integer (1) String (50) String (255) String (50) String (30) String (no length limit) Integer (1) String (50) String (255) PayPal Services Implementation Guide September

91 Chapter 4 Requesting Services with the SCMP API Table 17 Button Create Reply Fields (Continued) Reply Field Description Data Type & Length paypal_button_ create_time paypal_button_ create_trans_ref_no paypal_button_create_ unencrypted_form_data Time of the button creation request. The format is YYYY-MM- DDThhmmssZ. For example, T224757Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Reference number for the transaction that you use to reconcile your transactions. Unencrypted version of the button. Date and time (20) String (60) String (no length limit) request_id Unique identifier for the request generated by the client. String (26) request_token Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. String (256) Reply Flags The following table describes the reply flags for ics_paypal_button_create. The reply flags you receive are the same for either type of button. Table 18 Button Create Reply Flags Reply Flag DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Description Data provided is not consistent with the request. For example, you requested a product with negative cost. The request is missing a required field. System error. See the documentation for your CyberSource client (for important information about how to handle system errors and retries. The request timed out. The transaction was successful. PayPal Services Implementation Guide September

92 Chapter 4 Requesting Services with the SCMP API Processing a Preapproved Payment After the customer has accepted the billing agreement, you may process preapproved payments according to the agreement. Use ics_paypal_preapproved_payment to process each payment. To request the service, send a request with ics_applications=ics_paypal_ preapproved_payment. In the paypal_mp_id field you must include the customer's billing agreement identifier that you received when the customer accepted the billing agreement. See the description of mp_id in "Reply Variables for Creating a Billing Agreement," page 141. See Appendix B, "Examples for the SCMP API," on page 128 for example requests and replies. The only other ICS service that you can call with ics_paypal_preapproved_payment is ics_tax. See the Tax Calculation Implementation Guide. Request-Level Fields The following table lists the request-level fields for ics_paypal_preapproved_payment. Table 19 Preapproved Payment Request-Level Fields Request-Level Field Description Required/ Optional Data Type & Length bill_city City of the billing address. Required String (50) bill_country bill_state bill_zip currency Country of the billing address. Use the two-character ISO codes. See the Support Center for a list of codes. State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes. Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example: A1B 2C3 Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. Required String (2) Required if country is U.S. or Canada Required if country is U.S. or Canada String (2) String (10) Required String (5) PayPal Services Implementation Guide September

93 Chapter 4 Requesting Services with the SCMP API Table 19 Preapproved Payment Request-Level Fields (Continued) Request-Level Field Description Required/ Optional customer_ Customer s address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]). Optional String (255) customer_firstname Customer s first name. Required String (60) customer_lastname Customer s last name. Required String (60) grand_total_amount Grand total for the order. You must include either this field or offer0 and the offer-level field amount. See the information about offers and grand totals in Getting Started with CyberSource Advanced. See description Decimal (15) ics_applications ICS services to process for the request. Required String (255) link_to_request merchant_id merchant_ref_number offer0...n paypal_customer_ paypal_ _subject Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the SCMP API. Your CyberSource merchant ID. Use the same merchant_id for evaluation, testing, and production. Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced. Offers (line items of the order) for the request. You must include either offer0 and the offer-level field amount, or the request-level field grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced. Customer s address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]). Subject line of the confirmation that will be sent to the customer. Optional String (26) Required String (30) Required String (50) See description String (50) Optional String (255) Optional String (no length limit) paypal_item_name Name of purchased item. Optional String (no length limit) paypal_item_number Reference number of purchased item. Optional String (no length limit) paypal_memo Text entered by the customer in the Note field during enrollment. Optional Data Type & Length String (no length limit) paypal_mp_id Billing agreement identifier (the mp_id). Required String (19) PayPal Services Implementation Guide September

94 Chapter 4 Requesting Services with the SCMP API Table 19 Preapproved Payment Request-Level Fields (Continued) Request-Level Field Description Required/ Optional paypal_payment_type The type of PayPal payment funding source to use. Use one of the following values: Any (default): Any payment type is acceptable EcheckOnly: echeck InstantOnly: Instant only Make sure to provide the value exactly as shown above. Data Type & Length Optional String (11) timeout Number of seconds the system waits before the transaction times out. The default is 110 seconds. Optional Positive integer (3) Offer-Level Fields The following table describes the offer-level fields for ics_paypal_preapproved_ payment. Table 20 Preapproved Payment Offer-Level Fields Offer-Level Field Description Required/ Optional amount Per-item price of the product. You must include either this field or grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. See description Data Type & Length Decimal (15) merchant_product_sku Product s identifier code Optional String (30) product_code Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. Optional String (30) product_name Product s name. Optional String (30) PayPal Services Implementation Guide September

95 Chapter 4 Requesting Services with the SCMP API Table 20 Preapproved Payment Offer-Level Fields (Continued) Offer-Level Field Description Required/ Optional quantity tax_amount Quantity of the product being purchased. The default value is 1. Required if product_code for the offer is NOT default, stored_value, or one of the values related to shipping and/or handling. Total tax to apply to the product. This value cannot be negative. The tax_amount field is additive. For example, if you send the following offer lines: offer0=amount:10.00^quantity:1^tax_ amount:0.80 offer1=amount:20.00^quantity:1^tax_ amount:1.60 the total amount will be for $32.40, not $30.00 with $2.40 of tax included. The tax_amount and the amount must be in the same currency. See description Data Type & Length Nonnegative integer (10) Optional Decimal (15) Reply Fields The following table lists the reply fields for ics_paypal_preapproved_payment. Table 21 Preapproved Payment Reply Fields Reply Field Description Data Type & Length client_lib_version ics_rcode ics_rflag ics_rmsg merchant_ref_number Information about the client library used to request the transaction. One-digit code that indicates whether the entire request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the entire request. See Table 22, page 99 for a list of possible values. Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field, the returned value might contain corrupted characters. String (50) Integer (1) String (50) String (255) String (50) PayPal Services Implementation Guide September

96 Chapter 4 Requesting Services with the SCMP API Table 21 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypal_preapproved_ payment_desc paypal_preapproved_ payment_exchange_rate paypal_preapproved_ payment_fee_amount paypal_preapproved_ payment_mp_max paypal_preapproved_ payment_mp_status Value of the paypal_mp_desc field you provided when creating the billing agreement button. Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer's non-primary currency. If the customer chooses to pay in a currency other than the non-primary currency, the conversion occurs in the customer's account. String (no length limit) String (15) PayPal fee amount charged for the transaction. String (15) Monthly maximum payment amount. String (15) Current status of the billing agreement. This field will contain one of the following values: Active Canceled String (9) paypal_preapproved_ payment_payer paypal_preapproved_ payment_payer_business paypal_preapproved_ payment_payer_country paypal_preapproved_ payment_payer_id paypal_preapproved_ payment_payer_name paypal_preapproved_ payment_payer_status paypal_preapproved_ payment_payment_date paypal_preapproved_ payment_payment_gross_ amount Customer's PayPal account identifier (customer's address). Customer's business name if the customer has a PayPal Business or Premier account. Customer's country of residence. PayPal-generated unique customer ID. Customer's name. Status of the customer's address. This field will contain one of the following values: verified: Customer s PayPal account is Verified unverified: Customer s PayPal account is Unverified PayPal's timestamp for the payment. Example: 18:30:30 Jan 1, 2000 PST. The final amount charged including any shipping or taxes from your PayPal profile. String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (10) String (20) String (15) PayPal Services Implementation Guide September

97 Chapter 4 Requesting Services with the SCMP API Table 21 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypal_preapproved_ payment_payment_status paypal_preapproved_ payment_payment_type paypal_preapproved_ payment_pending_reason Status of the preapproved payment. This field will contain one of the following values: Completed Pending (see reasons in paypal_preapproved_ payment_pending_reason below) Failed Retry Indicates whether the payment is instant or delayed. This field will contain one of the following values: echeck instant Reason a payment is pending if paypal_preapproved_ payment_payment_status=pending. This field will contain one of the following values: address: Customer did not include a confirmed shipping address, and you have your Payment Receiving Preferences set to manually accept or deny each of these payments. echeck: Electronic check has not cleared yet. intl: You hold a non-u.s. account and do not have a withdrawal method. You must manually accept or deny this payment from your PayPal 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 the payment. You must manually accept or deny the payment. other: Payment is pending for a reason other than the other reasons listed here. Contact PayPal Customer Service. unilateral: The payment was made to an address that is not yet registered or confirmed. upgrade: Payment was made via credit card and you must upgrade your account to Business or Premier status to receive the funds. You could also get this status because you have reached the monthly limit for transactions on your account. verify: You are not yet verified. You must verify your account before you can accept the payment. String (9) String (7) String (14) PayPal Services Implementation Guide September

98 Chapter 4 Requesting Services with the SCMP API Table 21 Preapproved Payment Reply Fields (Continued) Reply Field Description Data Type & Length paypal_preapproved_ payment_rcode One-digit code that indicates whether the ics_paypal_ preapproved_payment request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful Integer (1) paypal_preapproved_ payment_rflag paypal_preapproved_ payment_rmsg paypal_preapproved_ payment_settle_amount paypal_preapproved_ payment_tax_amount paypal_preapproved_ payment_time paypal_preapproved_ payment_trans_ref_no paypal_preapproved_ payment_transaction_id paypal_preapproved_ payment_transaction_type One-word description of the result of the ics_paypal_ preapproved_payment request. See Table 22, page 99 for a list of possible values. Message that explains the reply flag paypal_preapproved_ payment_rflag. Do not display this message to the customer, and do not use this field to write an error handler. Amount deposited in your PayPal account after a currency conversion. String (50) String (255) String (15) Tax charged on the transaction. String (15) Time of the preapproved payment request. The format is YYYY-MM-DDThhmmssZ. For example, T224757Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Reference number for the transaction that you use to reconcile your transactions. PayPal's unique transaction ID for the payment. Type of PayPal payment. This field will contain the value mercht-pmt. Date and time (20) String (60) String (no length limit) request_id Unique identifier for the request generated by the client. String (26) request_token Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. String (256) PayPal Services Implementation Guide September

99 Chapter 4 Requesting Services with the SCMP API Reply Flags The following table describes the rflags for ics_paypal_preapproved_payment. Table 22 Preapproved Payment Reply Flags Reply Flag DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Description Data provided is not consistent with the request. For example, you requested a product with negative cost. The request is missing a required field. System error. See the documentation for your CyberSource client (SDK) for important information about how to handle system errors and retries. The request timed out. The transaction was successful. Canceling or Updating a Billing Agreement You can cancel a billing agreement or update a billing agreement with a new description of the goods and services. To do either of these, use ics_paypal_preapproved_update. You may not update the maximum amount for a billing agreement. To request the service, send a request with ics_applications=ics_paypal_ preapproved_update. Do not include any other ICS services in the request. See Appendix B, "Examples for the SCMP API," on page 128 for example requests and replies. You can view the details of a billing agreement in the Business Center. See "Billing Agreements," page 12 for more information. PayPal Services Implementation Guide September

100 Chapter 4 Requesting Services with the SCMP API Request-Level Fields The following table lists the request-level fields for ics_paypal_preapproved_update. The service uses no offer-level fields. Table 23 Billing Agreement Update Request-Level Fields Request-Level Field Description Required/ Optional Data Type & Length ics_applications ICS services to process for the request. Required String (255) merchant_id merchant_ref_number paypal_mp_desc paypal_mp_id paypal_mp_status timeout Your CyberSource merchant ID. Use the same merchant_ id for evaluation, testing, and production. Order reference or tracking number that you provided in the request. See the information about order tracking in Getting Started with CyberSource Advanced. Description of the goods or services associated with the billing agreement. Billing agreement identifier (the mp_id) that you received from PayPal. Set this field to Canceled to cancel the billing agreement. The value is case sensitive, so make sure to set it exactly as shown here. Number of seconds the system waits before the transaction times out. The default is 110 seconds. Required String (30) Required String (50) Optional String (no length limit) Required String (19) Optional String (8) Optional Positive integer (3) Reply Fields The following table lists the reply fields for ics_paypal_preapproved_update. Table 24 Billing Agreement Update Reply Fields Request Field Description Data Type & Length client_lib_version ics_rcode ics_rflag ics_rmsg Information about the client library used to request the transaction. One-digit code that indicates whether the entire request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the entire request. See Table 25, page 102 for a list of possible values. Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler. String (50) Integer (1) String (50) String (255) PayPal Services Implementation Guide September

101 Chapter 4 Requesting Services with the SCMP API Table 24 Billing Agreement Update Reply Fields (Continued) Request Field Description Data Type & Length merchant_ref_number paypal_preapproved_ update_desc paypal_preapproved_ update_mp_max paypal_preapproved_ update_mp_status paypal_preapproved_ update_payer paypal_preapproved_ update_payer_business paypal_preapproved_ update_payer_country paypal_preapproved_ update_payer_id paypal_preapproved_ update_payer_name paypal_preapproved_ update_payer_status paypal_preapproved_ update_rcode paypal_preapproved_ update_rflag paypal_preapproved_ update_rmsg Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Value of the paypal_mp_desc field you provided when creating the billing agreement button. Monthly maximum payment amount. Current status of the billing agreement. This field will contain one of the following values: Active Canceled Customer's PayPal account identifier (customer's address). Customer's business name if the customer has a PayPal Business or Premier account. Customer's country of residence. PayPal-generated unique customer ID. Customer's name. Status of the customer's address. This field will contain one of the following values: verified: Customer s PayPal account is Verified unverified: Customer s PayPal account is Unverified One-digit code that indicates whether the ics_paypal_ preapproved_update request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the ics_paypal_ preapproved_update request. See Table 25, page 102 for a list of possible values. Message that explains the reply flag paypal_preapproved_ update_rflag. Do not display this message to the customer, and do not use this field to write an error handler. String (50) String (no length limit) Decimal (15) String (9) String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (no length limit) String (10) Integer (1) String (50) String (255) PayPal Services Implementation Guide September

102 Chapter 4 Requesting Services with the SCMP API Table 24 Billing Agreement Update Reply Fields (Continued) Request Field Description Data Type & Length paypal_preapproved_ update_time paypal_preapproved_ update_trans_ref_no Time of the billing agreement update request. The format is YYYY-MM-DDThhmmssZ. For example, T224757Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Reference number for the transaction that you use to reconcile your transactions. Date and time (20) String (60) request_id Unique identifier for the request. String (26) request_token Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. String (256) Reply Flags The following table describes the rflags for ics_paypal_preapproved_update. Table 25 Billing Agreement Update Reply Flags Reply Flag DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Description Data provided is not consistent with the request. For example, you requested a product with negative cost. The request is missing a required field. System error. See the documentation for your CyberSource client for important information about how to handle system errors and retries. The request timed out. The transaction was successful. Processing a Credit Use ics_paypal_credit to perform a credit for a regular payment or a preapproved payment. For general information about refunding PayPal payments, see "PayPal Credits," page 13. Important You must perform the credit within 60 days of the payment request. At this time, you can perform only one credit for an order, for either a partial amount or the full amount of the payment. PayPal Services Implementation Guide September

103 Chapter 4 Requesting Services with the SCMP API To request the service, send a request with ics_applications=ics_paypal_credit. A PayPal credit is a follow-on service. It uses the request_id and request_token returned from a previous ics_paypal_preapproved_payment or ics_paypal_preapproved_ update request to link the credit to the payment. Send the request ID value in the paypal_ payment_request_id field and send the request token value in the order_request_token field. CyberSource uses these values to look up the customer s billing and account information from the original payment, so you do not have to supply those fields in the ics_ paypal_credit request. For information about the request token, see the information about follow-on services in Getting Started with CyberSource Advanced. When requesting the service, do not request any other ICS services. Request-Level Fields The following table lists the request-level fields for ics_paypal_credit. Table 26 Credit Request-Level Fields Request-Level Field Description Required / Optional currency grand_total_amount Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only. Amount of the credit. At this time, you can perform only one credit for an order, for either a partial amount or the full amount of the payment. You must include either this field or offer0 and the offerlevel field amount. See the information about offers and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative. Data Type & Length Required String (5) See description Decimal (15) ics_applications ICS services to process for the request. Required String (255) merchant_id merchant_ref_number Your CyberSource merchant ID. Use the same merchant_ id for evaluation, testing, and production. Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced. Required String (30) Required String (50) offer0...n Offers (line items of the order) for the request. Optional String (50) order_request_token The request token value returned from a previous request. This value links the previous request to the current followon request. This field is an encoded string that does not contain any confidential information, such as account numbers or card verification numbers. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. Required String (256) PayPal Services Implementation Guide September

104 Chapter 4 Requesting Services with the SCMP API Table 26 Credit Request-Level Fields (Continued) Request-Level Field Description Required / Optional paypal_payment_ request_id paypal_payment_ request_token timeout Request ID from the PayPal payment reply. Required String (26) The request_token value returned from a previous request for ics_paypal_preapproved_payment or ics_ paypal_preapproved_update. The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. Number of seconds the system waits before the transaction times out. The default is 110 seconds. Optional Optional Data Type & Length String (256) Positive integer (3) Offer-Level Fields The following table describes the offer-level fields for ics_paypal_credit. Table 27 Credit Offer-Level Fields Offer-Level Field Description Required / Optional amount merchant_ product_sku product_code Per-item price of the product. You must include either this field or grand_total_amount in your request. See the information about request tokens in Getting Started with CyberSource Advanced. This value cannot be negative. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. See description Data Type & Length Decimal (15) Product s identifier code Optional String (30) Type of product. The default value is default. See "Product Codes," page 152 for a list of valid values. Optional String (30) product_name Product s name. Optional String (30) PayPal Services Implementation Guide September

105 Chapter 4 Requesting Services with the SCMP API Table 27 Credit Offer-Level Fields (Continued) Offer-Level Field Description Required / Optional quantity tax_amount Quantity of the product being returned. The default value is 1. Required if product_code for the offer is NOT default, stored_value, or one of the values related to shipping and/or handling. Total tax to apply to the product. This value cannot be negative. The tax_amount field is additive. For example, if you send the following offer lines: offer0=amount:10.00^quantity:1^tax_ amount:0.80 offer1=amount:20.00^quantity:1^tax_ amount:1.60 the total amount will be for $32.40, not $30.00 with $2.40 of tax included. The tax_amount and the amount must be in the same currency. See description Optional Data Type & Length Nonnegative integer (10) Decimal (15) Reply Fields The following table describes the reply fields for ics_paypal_credit. Table 28 Credit Reply Fields Reply Field Description Data Type & Length client_lib_version Information about the client library used to request the transaction. String (50) currency Currency used for the order. String (5) ics_rcode One-digit code that indicates whether the entire request was successful. The field contains one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful Integer (1) ics_rflag One-word description of the result of the entire request. See Table 29, page 106 for a list of possible values. String (50) ics_rmsg Message that explains the reply flag ics_rflag. String (255) merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. String (50) PayPal Services Implementation Guide September

106 Chapter 4 Requesting Services with the SCMP API Table 28 Credit Reply Fields (Continued) Reply Field Description Data Type & Length paypal_credit_amount Amount of the credit. Decimal (15) paypal_credit_rcode One-digit code that indicates whether the ics_paypal_credit request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful Integer (1) paypal_credit_rflag One-word description of the result of the ics_paypal_credit request. See Table 29, page 106 for a list of possible values. String (50) paypal_credit_rmsg Message that explains the reply flag paypal_credit_rflag. String (255) paypal_credit_time paypal_credit_ trans_ref_no Time of the PayPal credit request. The format is YYYY-MM- DDThhmmssZ. For example, T224757Z is equal to August 11, 2002, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Reference number for the transaction that you use to reconcile your CyberSource reports with your processor reports. Date and Time (20) String (60) request_id Identifier for the request generated by the client. String (26) request_token Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters. For more information, see the information about request tokens in Getting Started with CyberSource Advanced. String (256) Reply Flags The following table describes the rflags for ics_paypal_credit. Table 29 Credit Reply Flags Reply Flag DPAYMENTREFUSED DINVALIDDATA DMISSINGFIELD ESYSTEM Description A request was made to credit an order for which there is no corresponding, unused payment record. Occurs if there was not a previously successful ics_paypal_button_ create or ics_paypal_preapproved_payment request, or if the previously successful payment has already been used by another ics_paypal_credit request. Data provided is not consistent with the request. For example, you requested a product with negative cost. The request is missing a required field. System error. See the documentation for your CyberSource client for important information about how to handle system errors and retries. PayPal Services Implementation Guide September

107 Chapter 4 Requesting Services with the SCMP API Table 29 Credit Reply Flags (Continued) Reply Flag ETIMEOUT SOK Description The request timed out. The transaction was successful. Testing You can use CyberSource s regular testing environment for sending test transactions. Make sure your requests specify server_host=ics2testa.ic3.com and server_ port=80. The buttons generated by CyberSource s test system submit the form to PayPal s Sandbox test environment ( You need to set up your Sandbox account as soon as you begin creating your implementation. See PayPal s Sandbox User Guide for instructions. Always log in to the Sandbox before clicking any of your test buttons. Then when you click your test button, you will automatically go to the Sandbox site, which mimics the live PayPal site that the customer logs in to. PayPal Services Implementation Guide September

108 Creating a Shopping Cart Button CHAPTER 5 CyberSource s recommended solution is to use the regular payment button where the button type = buy. This is PayPal s Buy Now button, which uses an aggregate amount for the total order. However, if you want to specify information about the individual items the customer is purchasing, you can create a Shopping Cart button instead. Note You should still read the information about creating a regular Buy Now button as this appendix covers only the differences between creating a Shopping Cart button and a regular Buy Now button. See either Chapter 3, "Creating Buttons," on page 37 (if using the Simple Order API) or Chapter 4, "Creating Buttons," on page 72 (if using the SCMP API). Step 1 Step 2 In your request to create the button, set the button type to shopping_cart instead of buy. To specify the information about the different items, use the numbered item-specific fields listed below. Start the numbering with 1. See the example requests below. All of the fields are optional. See PayPal s Merchant User Manual and Integration Guide for more information about on0_# and the similar fields. paypal_item_name_# paypal_shipping_# on0_# paypal_item_number_# paypal_handling_# os0_# paypal_quantity_# paypal_tax_# on1_# paypal_amount_# paypal_shipping2_# os1_# Note Do not include any of CyberSource s standard API fields for items (for example, do not use item_0_unitprice if using the Simple Order API, or offer0 with amount if using the SCMP API, and so on). Also, you do not need to provide a grand total for the offer. Step 3 If you want to specify cart-wide tax or handling charges, use these fields: paypal_tax_cart: This value overrides any item-level (paypal_tax_#) values or profile-based tax. paypal_handling_cart: This value is added to any item-level shipping or handling charges you have specified with paypal_shipping_# and/or paypal_handling_# values. PayPal Services Implementation Guide September

109 Chapter 5 Creating a Shopping Cart Button Step 4 Send CyberSource the request as you would for a regular payment button. The reply you receive contains the same API reply fields as for a regular payment button. If you have configured your CyberSource account so that you are forwarded your IPN messages, you will see separate numbered IPN variables for each item. The variables are included in the list in "IPN Variables for Regular Payments," page 144. PayPal Services Implementation Guide September

110 Examples for the Simple Order API APPENDIX A Note The buttons in the examples include line breaks to make it easier to see the different variables and their values. The actual buttons will not include line breaks. The encrypted buttons in the examples have been shortened for illustration. The actual length of the encrypted information is about characters. PayPal Services Implementation Guide September

111 Appendix A Examples for the Simple Order API Name-Value Pair Examples Creating a Regular Payment Button Example Request paypalbuttoncreateservice_run=true paypalbuttoncreateservice_buttontype=buy merchantid=infodev merchantreferencecode=482046c3a7e9xyz billto_firstname=joe billto_lastname=smith billto_street1=1040 Elm St. billto_city=san Jose billto_state=ca billto_postalcode=95127 billto_country=us shipto_firstname=joe shipto_lastname=smith shipto_street1=1040 Elm St. shipto_city=san Jose shipto_state=ca shipto_postalcode=95127 shipto_country=us purchasetotals_grandtotalamount=25.99 purchasetotals_taxamount=2.55 purchasetotals_freightamount=4.95 purchasetotals_currency=usd paypal_cancel_return= paypal_return= paypal_item_name=nouveau Lamp paypal_item_number= PayPal Services Implementation Guide September

112 Appendix A Examples for the Simple Order API Example Reply requestid= merchantreferencecode=482046c3a7e9xyz decision=accept reasoncode=100 paypalbuttoncreatereply_reasoncode=100 paypalbuttoncreatereply_buttontype=buy paypalbuttoncreatereply_amount=33.49 purchasetotals_currency=usd paypalbuttoncreatereply_requestdatetime= t18:49:55z paypalbuttoncreatereply_reconconciliationid=ryxwmqx04mc9 paypalbuttoncreatereply_unencryptedformdata= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="first_name" value="joe"> <input type="hidden" name="smith" value="smith"> <input type="hidden" name="address1" value="1040 Elm St"> <input type="hidden" name="city" value="san Jose"> <input type="hidden" name="state" value="ca"> <input type="hidden" name="zip" value="95127"> <input type="hidden" name="amount" value="25.99"> <input type="hidden" name="tax" value="2.55"> <input type="hidden" name="handling" value="0.00"> <input type="hidden" name="shipping" value="4.95"> <input type="hidden" name="item_number"value=" "> <input type="hidden" name="cancel_return" value=" <input type="hidden" name="undefined_quantity" value="0"> <input type="hidden" name="quantity" value="0"> <input type="hidden" name="return" value=" <input type="hidden" name="item_name" value="noveau Lamp"> <input type="hidden" name="shipping2" value="0.00"> <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="invoice" value="ryxwmqx04mc9"> <input type="hidden" name="custom" value="ryxwmqx04mc9, ,482046c3a7e9xyz"></ form>paypalbuttoncreatereply_encryptedformdata= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="encrypted" value= "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM -----END PKCS7-----"></form> PayPal Services Implementation Guide September

113 Appendix A Examples for the Simple Order API Creating a Billing Agreement Button Example Request paypalbuttoncreateservice_run=true paypalbuttoncreateservice_buttontype=preapproved_billing_agreement merchantid=infodev merchantreferencecode=482046c3a7e94f5 billto_firstname=joe billto_lastname=smith billto_street1=1040 Elm St. billto_city=san Jose billto_state=ca billto_postalcode=95127 billto_country=us paypal_return= paypal_mp_cycle_start=1 paypal_mp_desc=gold Package Web Access at paypal_mp_max=20.00 paypal_mp_test_amount=10.00 PayPal Services Implementation Guide September

114 Appendix A Examples for the Simple Order API Example Reply requestid= merchantreferencecode=482046c3a7e94f3 decision=accept reasoncode=100 paypalbuttoncreatereply_reasoncode=100 paypalbuttoncreatereply_buttontype=preapproved_billing_agreement paypalbuttoncreatereply_requestdatetime= t18:49:55z paypalbuttoncreatereply_reconconciliationid=ryxwmqx04mc1 paypalbuttoncreatereply_unencryptedformdata= <form action=" method="post"> <input type="submit" name="submit" value="approve Agreement"> <input type="hidden" name="cmd" value="_xclick-merchant"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="mp_max" value="20.00"> <input type="hidden" name="mp_cycle_start" value="1"> <input type="hidden" name="mp_test_amount" value="10.00"> <input type="hidden" name="return" value=" <input type="hidden" name="mp_desc" value="gold Package Web Access at <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="mp_custom" value="ryxwmqx04mc1, ,482046c3a7e94f3"></form> paypalbuttoncreatereply_encryptedformdata= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_xclick-merchant"> <input type="hidden" name="encrypted" value= "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM -----END PKCS7-----"></form> PayPal Services Implementation Guide September

115 Appendix A Examples for the Simple Order API Processing a Preapproved Payment Example Request paypalpreapprovedpaymentservice_run=true paypalpreapprovedpaymentservice_mpid=b abcdefgh merchantid=infodev merchantreferencecode=482046c3a7e94f3 billto_firstname=joe billto_lastname=smith billto_street1=1040 Elm St. billto_city=san Jose billto_state=ca billto_postalcode=95127 billto_country=us purchasetotals_grandtotalamount=19.95 purchasetotals_currency=usd paypal_ _subject=your Monthly Payment for Gold Package at Example Reply requestid= merchantreferencecode=482046c3a7e94f3 decision=accept reasoncode=100 paypalpreapprovedpaymentreply_reasoncode=100 purchasetotals_currency=usd paypalpreapprovedpaymentreply_requestdatetime= t18:49:55z paypalpreapprovedpaymentreply_reconconciliationid=ryxwmqx04mc2 paypalpreapprovedpaymentreply_payerstatus=verified paypalpreapprovedpaymentreply_payername=joe Smith paypalpreapprovedpaymentreply_transactiontype=mercht-pmt paypalpreapprovedpaymentreply_feeamount=0.00 paypalpreapprovedpaymentreply_payercountry=us paypalpreapprovedpaymentreply_pendingreason=none paypalpreapprovedpaymentreply_paymentstatus=completed paypalpreapprovedpaymentreply_mpstatus=active [email protected] paypalpreapprovedpaymentreply_payerid=s6d5mjqsvyx94 paypalpreapprovedpaymentreply_transactionid=56k11500ry paypaypalpreapprovedpaymentreply_desc=gold Package Web Access at paypalpreapprovedpaymentreply_mpmax=20.00 paypalpreapprovedpaymentreply_paymenttype=instant paypalpreapprovedpaymentreply_paymentdate=10:50:30 May 27, 2005 PST paypalpreapprovedpaymentreply_paymentgrossamount=19.95 paypalpreapprovedpaymentreply_taxamount=0.00 PayPal Services Implementation Guide September

116 Appendix A Examples for the Simple Order API Updating a Billing Agreement This example cancels the billing agreement. You could also update the billing agreement with a different description. Example Request paypalpreapprovedupdateservice_run=true paypalpreapprovedupdateservice_mpid=b abcdefgh merchantid=infodev merchantreferencecode=482046c3a7e94f3 paypal_mp_status=canceled Example Reply requestid= merchantreferencecode=482046c3a7e94f3 decision=accept reasoncode=100 paypalpreapprovedupdatereply_reasoncode=100 paypalpreapprovedupdatereply_requestdatetime= t18:49:55z paypalpreapprovedupdatereply_reconconciliationid=ryxwmqx04wc4 paypaypalpreapprovedupdatereply_desc=gold Package Web Access at paypalpreapprovedupdatereply_mpmax=20.00 paypalpreapprovedupdatereply_mpstatus=canceled [email protected] paypalpreapprovedupdatereply_payercountry=us paypalpreapprovedupdatereply_payerid=s6d5mjqsvyx94 paypalpreapprovedupdatereply_payername=joe Smith paypalpreapprovedupdatereply_payerstatus=verified Processing a Credit Example Request paypalcreditservice_run=true merchantid=infodev merchantreferencecode=482046c3a7e94f3 paypalcreditservice_paypalpaymentrequestid= purchasetotals_currency=usd purchasetotals_grandtotalamount=10.00 PayPal Services Implementation Guide September

117 Appendix A Examples for the Simple Order API Example Reply requestid= merchantreferencecode=482046c3a7e94f5 decision=accept reasoncode=100 paypalcreditreply_reasoncode=100 paypalcreditreply_requestdatetime= t18:49:55z paypalcreditreply_reconconciliationid=ryx9483qx04wc4 paypalcreditreply_amount=10.00 purchasetotals_currency=usd Creating a Shopping Cart Button Example Request paypalbuttoncreateservice_run=true paypalbuttoncreateservice_buttontype=shopping_cart merchantid=infodev merchantreferencecode=482046c3a7e94f5 paypal_cancel_return= paypal_return= paypal_item_name_1=book paypal_item_number_1= paypal_amount_1=25.95 paypal_quantity_1=1 paypal_shipping_1=3.95 paypal_shipping2_1=0.00 paypal_handling_1=0.00 paypal_tax_1=0.00 paypal_item_name_2=dvd paypal_item_number_2= paypal_amount_2=18.95 paypal_quantity_2=1 paypal_shipping_2=0.00 paypal_shipping2_2=0.00 paypal_handling_2=0.00 paypal_tax_2=0.00 // Include the API fields for the billing // and shipping information here PayPal Services Implementation Guide September

118 Appendix A Examples for the Simple Order API XML Examples Creating a Regular Payment Button Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f5</merchantreferencecode> <billto> <firstname>joe</firstname> <lastname>smith</lastname> <street1>1040 Elm St.</street1> <city>san Jose</city> <state>ca</state> <postalcode>95127</postalcode> <country>us</country> </billto> <shipto> <firstname>joe</firstname> <lastname>smith</lastname> <street1>1040 Elm St.</street1> <city>san Jose</city> <state>ca</state> <postalcode>95127</postalcode> <country>us</country> </shipto> <purchasetotals> <currency>usd</currency> <taxamount>2.55</taxamount> <grandtotalamount>25.99</grandtotalamount> <freightamount>4.95</freightamount> </purchasetotals> <paypal> <cancel_return> <return> <item_name>nouveau Lamp</item_name> <item_number> </item_number> </paypal> <paypalbuttoncreateservice run="true"> <buttontype>buy</buttontype> </paypalbuttoncreateservice> </requestmessage> PayPal Services Implementation Guide September

119 Appendix A Examples for the Simple Order API Example Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:merchantreferencecode>482046c3a7e94f5 </c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>usd</c:currency> </c:purchasetotals> <c:paypalbuttoncreatereply> <c:reasoncode>100</c:reasoncode> <c:encryptedformdata> <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="encrypted" value= "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM -----END PKCS7-----"></form> </c:encryptedformdata> <c:unencryptedformdata> <form action=" method="post"> PayPal Services Implementation Guide September

120 Appendix A Examples for the Simple Order API <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="first_name" value="joe"> <input type="hidden" name="smith" value="smith"> <input type="hidden" name="address1" value="1040 Elm St"> <input type="hidden" name="city" value="san Jose"> <input type="hidden" name="state" value="ca"> <input type="hidden" name="zip" value="95127"> <input type="hidden" name="amount" value="25.99"> <input type="hidden" name="tax" value="2.55"> <input type="hidden" name="handling" value="0.00"> <input type="hidden" name="shipping" value="4.95"> <input type="hidden" name="item_number"value=" "> <input type="hidden" name="cancel_return" value=" <input type="hidden" name="undefined_quantity" value="0"> <input type="hidden" name="quantity" value="0"> <input type="hidden" name="return" value=" <input type="hidden" name="item_name" value="noveau Lamp"> <input type="hidden" name="shipping2" value="0.00"> <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="invoice" value="ryxwmqx04mc9"> <input type="hidden" name="custom" value="ryxwmqx04mc9, ,482046c3a7e94f5"></form> </c:unencryptedformdata> <c:requestdatetime>= t18:49:55z</c:requestdatetime> <c:recondiliationid>ryxwmqx04mc9</c:reconciliationid> <c:buttontype>buy</c:buttontype> </c:paypalbuttoncreatereply> </c:replymessage> PayPal Services Implementation Guide September

121 Appendix A Examples for the Simple Order API Creating a Billing Agreement Button Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f5</merchantreferencecode> <billto> <firstname>joe</firstname> <lastname>smith</lastname> <street1>1040 Elm St.</street1> <city>san Jose</city> <state>ca</state> <postalcode>95127</postalcode> <country>us</country> </billto> <paypal> <return> <mp_cycle_start>1</mp_cycle_start> <mp_desc>gold Package Web Access at <mp_test_amount>10.00</mp_test_amount> </paypal> <paypalbuttoncreateservice run="true"> <buttontype>preapproved_billing_agreement</buttontype> </paypalbuttoncreateservice> </requestmessage> PayPal Services Implementation Guide September

122 Appendix A Examples for the Simple Order API Example Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:merchantreferencecode>482046c3a7e94f3 </c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:paypalbuttoncreatereply> <c:reasoncode>100</c:reasoncode> <c:encryptedformdata> <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="encrypted" value= "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM -----END PKCS7-----"></form> </c:encryptedformdata> <c:unencryptedformdata> <form action=" method="post"> <input type="submit" name="submit" value="approve Agreement"> <input type="hidden" name="cmd" value="_xclick-merchant"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="mp_max" value="20.00"> <input type="hidden" name="mp_cycle_start" value="1"> <input type="hidden" name="mp_test_amount" value="10.00"> <input type="hidden" name="return" value=" <input type="hidden" name="mp_desc" value="gold Package Web Access at <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="mp_custom" value="ryxwmqx04mc1, ,482046c3a7e94f3"></form> </c:unencryptedformdata> <c:requestdatetime> t18:49:55z</c:requestdatetime> <c:recondiliationid>ryxwmqx04mc1</c:reconciliationid> <c:buttontype>preapproved_billing_agreement</c:buttontype> </c:paypalbuttoncreatereply> </c:replymessage> PayPal Services Implementation Guide September

123 Appendix A Examples for the Simple Order API Processing a Preapproved Payment Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f3</merchantreferencecode> <billto> <firstname>joe</firstname> <lastname>smith</lastname> <street1>1040 Elm St.</street1> <city>san Jose</city> <state>ca</state> <postalcode>95127</postalcode> <country>us</country> </billto> <purchasetotals> <currency>usd</currency> <grandtotalamount>19.95</grandtotalamount> </purchasetotals> <paypal> < _subject>your Monthly Payment for Gold Package at _subject> </paypal <paypalpreapprovedpaymentservice run="true"> <mpid>b abcdefgh</mpid> </paypalpreapprovedpaymentservice> </requestmessage> PayPal Services Implementation Guide September

124 Appendix A Examples for the Simple Order API Example Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:merchantreferencecode>482046c3a7e94f5 </c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>usd</c:currency> </c:purchasetotals> <c:paypalpreapprovedpaymentreply> <c:reasoncode>100</c:reasoncode> <c:requestdatetime> t18:49:55z</c:requestdatetime> <c:recondiliationid>ryxwmqx04mc2</c:reconciliationid> <c:payerstatus>verified</c:payerstatus> <c:payername>joe Smith</c:payerName> <c:transactiontype>mercht-pmt</c:transactiontype> <c:feeamount>0.00</c:feeamount> <c:payercountry>us</c:payercountry> <c:pendingreason>none</c:pendingreason> <c:paymentstatus>completed</c:paymentstatus> <c:mpstatus>active</c:mpstatus> <c:payer>[email protected]</c:payer> <c:payerid>s6d5mjqsvyx94</c:payerid> <c:transactionid>56k11500ry </c:transactionid> <c:desc>gold Package Web Access at <c:mpmax>20.00</c:mpmax> <c:paymenttype>instant</c:paymenttype> <c:paymentdate>10:50:30 Apr 27, 2005 PST</c:paymentDate> <c:paymentgrossamount>19.95</c:paymentgrossamount> <c:taxamount>0.00</c:taxamount> </c:paypalpreapprovedpaymentreply> </c:replymessage> PayPal Services Implementation Guide September

125 Appendix A Examples for the Simple Order API Updating a Billing Agreement This example cancels the billing agreement. You could also update the billing agreement with a different description. Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f3</merchantreferencecode> <paypal> <mp_status>canceled</mp_status> </paypal> <paypalpreapprovedupdateservice run="true"> <mpid>b abcdefgh</mpid> </paypalpreapprovedupdateservice> </requestmessage> Example Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:merchantreferencecode>482046c3a7e94f3 </c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <paypalpreapprovedupdatereply> <c:reasoncode>100</c:reasoncode> <c:requestdatetime> t18:49:55z</c:requestdatetime> <c:reconconciliationid>ryxwmqx04wc4</c:reconconciliationid> <c:payerstatus>verified</c:payerstatus> <c:payername>joe Smith</c:payerName> <c:payercountry>us</c:payercountry> <c:mpstatus>canceled</c:mpstatus> <c:payer>[email protected]</c:payer> <c:payerid>s6d5mjqsvyx94</c:payerid> <c:desc>gold Package Web Access at <c:mpmax>20.00</c:mpmax> </c:paypalpreapprovedpaymentreply> </c:replymessage> PayPal Services Implementation Guide September

126 Appendix A Examples for the Simple Order API Processing a Credit Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.37"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f3</merchantreferencecode> <purchasetotals> <currency>usd</currency> <grandtotalamount>10.00</grandtotalamount> </purchasetotals> <paypalcreditservice run="true"> <paypalpaymentrequestid> </paypalpaymentrequestid> </paypalcreditservice> </requestmessage> Example Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.37"> <c:merchantreferencecode>482046c3a7e94f3 </c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <purchasetotals> <c:currency>usd</c:currency> </c:purchasetotals> <c:paypalcreditreply> <c:reasoncode>100</c:reasoncode> <c:amount>10.00</c:amount> <c:requestdatetime> t18:49:55z</c:requestdatetime> <c:reconconciliationid>ryx9483qx04wc4</c:reconconciliationid> </c:paypalcreditreply> </c:replymessage> PayPal Services Implementation Guide September

127 Appendix A Examples for the Simple Order API Creating a Shopping Cart Button Example Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f5</merchantreferencecode> <billto> <!-- fill in billing information here --> </billto> <shipto> <!-- fill in shipping information here --> </shipto> <purchasetotals> <currency>usd</currency> </purchasetotals> <paypal> <item_name_1>book</item_name_1> <item_number_1>999999</item_number_1> <amount_1>25.95</amount_1> <quantity_1>1</quantity_1> <shipping_1>3.95</shipping_1> <shipping2_1>0.00</shipping2_1> <handling_1>0.00</handling_1> <tax_1>0.00</tax_1> <item_name_2>dvd</item_name_2> <item_number_2>777777</item_number_2> <amount_2>18.95</amount_2> <quantity_2>1</quantity_2> <shipping_2>0.00</shipping_2> <shipping2_2>0.00</shipping2_2> <handling_2>0.00</handling_2> <tax_2>0.00</tax_2> </paypal> <paypalbuttoncreateservice run="true"> <buttontype>shopping_cart</buttontype> </paypalbuttoncreateservice> </requestmessage> PayPal Services Implementation Guide September

128 Examples for the SCMP API APPENDIX B The buttons in the examples include line breaks to make it easier to see the different variables and their values. The actual buttons will not include line breaks. The encrypted buttons in the examples have been shortened for illustration. The actual length of the encrypted information is about characters. Creating a Regular Payment Button Example Request ics_applications=ics_paypal_button_create merchant_id=infodev merchant_ref_number=482046c3a7e9xyz button_type=buy customer_firstname=joe customer_lastname=smith bill_address1=1040 Elm St. bill_city=san Jose bill_state=ca bill_zip=95127 bill_country=us ship_to_firstname=joe ship_to_lastname=smith ship_to_address1=1040 Elm St. ship_to_city=san Jose ship_to_state=ca ship_to_zip=95127 ship_to_country=us grand_total_amount=25.99 total_tax_amount=2.55 freight_amount=4.95 currency=usd paypal_cancel_return= paypal_return= paypal_item_name=nouveau Lamp paypal_item_number= server_host=ics2testa.ic3.com server_port=80 PayPal Services Implementation Guide September

129 Appendix B Examples for the SCMP API Example Reply request_id= request_token=aa4jurwguallqxmugwxswvdps1birk5imuwa2ycv merchant_ref_number=482046c3a7e9xyz ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. paypal_button_create_rcode=1 paypal_button_create_rflag=sok paypal_button_create_rmsg=request was processed successfully. PayPal Services Implementation Guide September

130 Appendix B Examples for the SCMP API paypal_button_create_button_type=buy paypal_button_create_amount=33.49 currency=usd paypal_button_create_time= t184955z paypal_button_create_trans_ref_no=ryxwmqx04mc9 paypal_button_create_unencrypted_form_data= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="first_name" value="joe"> <input type="hidden" name="smith" value="smith"> <input type="hidden" name="address1" value="1040 Elm St"> <input type="hidden" name="city" value="san Jose"> <input type="hidden" name="state" value="ca"> <input type="hidden" name="zip" value="95127"> <input type="hidden" name="amount" value="25.99"> <input type="hidden" name="tax" value="2.55"> <input type="hidden" name="handling" value="0.00"> <input type="hidden" name="shipping" value="4.95"> <input type="hidden" name="item_number"value=" "> <input type="hidden" name="cancel_return" value=" paypalcancel.example.com"> <input type="hidden" name="undefined_quantity" value="1"> <input type="hidden" name="quantity" value="0"> <input type="hidden" name="return" value=" paypalsuccess.example.com"> <input type="hidden" name="item_name" value="noveau Lamp"> <input type="hidden" name="shipping2" value="0.00"> <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="undefined_quantity" value="1"> <input type="hidden" name="quantity" value="0"> <input type="hidden" name="return" value=" paypalsuccess.example.com"> <input type="hidden" name="return" value=" paypalsuccess.example.com"> <input type="hidden" name="item_name" value="noveau Lamp"> <input type="hidden" name="shipping2" value="0.00"> <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="invoice" value="ryxwmqx04mc9"> <input type="hidden" name="custom" value="ryxwmqx04mc9, ,482046c3a7e9xyz"></form> PayPal Services Implementation Guide September

131 Appendix B Examples for the SCMP API paypal_button_create_encrypted_form_data= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="encrypted" value= "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhM CVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQ EBAQUABIGAg0SFsADkAz5l03qK8we8z3zt86F9IZB8q8J+oCSjmBWgrZdh+VKHgPL2SKuRG rifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/r7hqzd/e1isljufz9/ikqo2hk/ wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/xmlpuoljanqnx2mvmi85hhpmacam -----END PKCS7-----"></form> client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.5 PayPal Services Implementation Guide September

132 Appendix B Examples for the SCMP API Creating a Billing Agreement Button Example Request ics_applications=ics_paypal_button_create merchant_id=infodev merchant_ref_number=482046c3a7e94f5 button_type=preapproved_billing_agreement customer_firstname=joe customer_lastname=smith bill_address1=1040 Elm St. bill_city=san Jose bill_state=ca bill_zip=95127 bill_country=us paypal_return= paypal_mp_cycle_start=1 paypal_mp_desc=gold Package Web Access at paypal_mp_max=20.00 paypal_mp_test_amount=10.00 server_host=ics2testa.ic3.com server_port=80 PayPal Services Implementation Guide September

133 Appendix B Examples for the SCMP API Example Reply request_id= request_token=rwgual5imuwawxaa4jus1birk2rk5imuycv merchant_ref_number=482046c3a7e94f3 ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. paypal_button_create_rcode=1 paypal_button_create_rflag=sok paypal_button_create_rmsg=request was processed successfully. paypal_button_create_button_type=preapproved_billing_agreement paypal_button_create_amount=33.49 currency=usd paypal_button_create_time= t184955z paypal_button_create_trans_ref_no=ryxwmqx04mc1 paypal_button_create_unencrypted_form_data= <form action=" method="post"> <input type="submit" name="submit" value="approve Agreement"> <input type="hidden" name="cmd" value="_xclick-merchant"> <input type="hidden" name="business" value="[email protected]"> <input type="hidden" name="mp_max" value="20.00"> <input type="hidden" name="mp_cycle_start" value="1"> <input type="hidden" name="mp_test_amount" value="10.00"> <input type="hidden" name="return" value=" <input type="hidden" name="mp_desc" value="gold Package Web Access at <input type="hidden" name="currency_code" value="usd"> <input type="hidden" name="bn" value="cybersource"> <input type="hidden" name="notify_url" value=" <input type="hidden" name="mp_custom" value="ryxwmqx04mc1, ,482046c3a7e94f3"></form> paypal_button_create_encrypted_form_data= <form action=" method="post"> <input type="image" src=" border="0" name="submit"> <input type="hidden" name="cmd" value="_s-xclick"> <input type="hidden" name="encrypted" value=" "-----BEGIN PKCS MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w e8z3zt86f9izb8q8j+ocsjmbwgrzdh+vkhgpl2skurgrifwxdcgfojonjyk5ekexescmr/ezruwzipumnkay/ r7hqzd/e1isljufz9/ikqo2hk/wrq5vyil22mgn0fy8gz6cbmm76ceyojoe/ XmlpUOLjANQnx2MVMI85hhpMAcaM -----END PKCS7-----"></form> PayPal Services Implementation Guide September

134 Appendix B Examples for the SCMP API Processing a Preapproved Payment Example Request ics_applications=ics_paypal_preapproved_payment merchant_id=infodev merchant_ref_number=482046c3a7e94f3 customer_firstname=joe customer_lastname=smith bill_address1=1040 Elm St. bill_city=san Jose bill_state=ca bill_zip=95127 bill_country=us grand_total_amount=19.95 currency=usd paypal_mp_id=b abcdefgh paypal_ _subject=your Monthly Payment for Gold Package at server_host=ics2testa.ic3.com server_port=80 Example Reply request_id= request_token=aa4jurwguallqxmugwxswvdps1birk5imuwa2ycv merchant_ref_number=482046c3a7e94f3 ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. paypal_preapproved_payment_rcode=1 paypal_preapproved_payment_rflag=sok PayPal Services Implementation Guide September

135 Appendix B Examples for the SCMP API paypal_preapproved_payment_rmsg=request was processed successfully. currency=usd paypal_preapproved_payment_time= t184955z paypal_preapproved_payment_trans_ref_no=ryxwmqx04mc2 paypal_preapproved_payment_desc=gold Package Web Access at paypal_preapproved_payment_fee_amount=0.00 paypal_preapproved_payment_mp_max=20.00 paypal_preapproved_payment_mp_status=active [email protected] paypal_preapproved_payment_payer_country=us paypal_preapproved_payment_payer_id=s6d5mjqsvyx94 paypal_preapproved_payment_payer_name=joe Smith paypal_preapproved_payment_payer_status=verified paypal_preapproved_payment_payment_date=10:50:30 May 27, 2005 PST paypal_preapproved_payment_payment_gross_amount=19.95 paypal_preapproved_payment_tax_amount=19.95 paypal_preapproved_payment_payment_status=completed paypal_preapproved_payment_payment_type=instant paypal_preapproved_payment_transaction_id=56k11500ry paypal_preapproved_payment_pending_reason=none paypal_preapproved_payment_transaction_type=mercht-pmt client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.5 PayPal Services Implementation Guide September

136 Appendix B Examples for the SCMP API Updating a Billing Agreement This example cancels the billing agreement. You could also update the billing agreement with a different description. Example Request ics_applications=ics_paypal_preapproved_update merchant_id=infodev merchant_ref_number=482046c3a7e94f3 paypal_mp_ip=b abcdefgh paypal_mp_status=canceled server_host=ics2testa.ic3.com server_port=80 PayPal Services Implementation Guide September

137 Appendix B Examples for the SCMP API Example Reply request_id= request_token=aa4jurwguallqxmugwxswvdps1birk5imuwa2ycv merchant_ref_number=482046c3a7e94f3 ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. paypal_preapproved_update_rcode=1 paypal_preapproved_update_rflag=sok paypal_preapproved_update_rmsg=request was processed successfully. currency=usd paypal_preapproved_update_time= t184955z paypal_preapproved_update_trans_ref_no=ryxwmqx04wc4 paypal_preapproved_update_desc=gold Package Web Access at paypal_preapproved_update_mp_max=20.00 paypal_preapproved_update_mp_status=canceled [email protected] paypal_preapproved_update_payer_country=us paypal_preapproved_update_payer_id=s6d5mjqsvyx94 paypal_preapproved_update_payer_name=joe Smith paypal_preapproved_update_payer_status=verified client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.5 PayPal Services Implementation Guide September

138 Appendix B Examples for the SCMP API Processing a Credit Example Request ics_applications=ics_paypal_credit merchant_id=infodev merchant_ref_number=482046c3a7e94f5 paypal_payment_request_id= order_request_token=aa4jurwguallqxmugwxswvdps1birk5imuwa2ycv currency=usd grand_total_amount=10.00 server_host=ics2testa.ic3.com server_port=80 Example Reply request_id= request_token=aa4jurwguallqxmugwxswvdps1birk5imuwa2ycv merchant_ref_number=482046c3a7e94f5 ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. paypal_credit_rcode=1 paypal_credit_rflag=sok paypal_credit_rmsg=request was processed successfully. paypal_credit_time= t18:49:55z paypal_credit_trans_ref_no=ryx9483qx04wc4 paypal_credit_amount=10.00 currency=usd client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.5 PayPal Services Implementation Guide September

139 Appendix B Examples for the SCMP API Creating a Shopping Cart Button Example Request ics_applications=ics_paypal_button_create button_type=shopping_cart merchant_id=infodev merchant_ref_number=482046c3a7e94f5 paypal_cancel_return= paypal_return= paypal_item_name_1=book paypal_item_number_1= paypal_amount_1=25.95 paypal_quantity_1=1 paypal_shipping_1=3.95 paypal_shipping2_1=0.00 paypal_handling_1=0.00 paypal_tax_1=0.00 paypal_item_name_2=dvd paypal_item_number_2= paypal_amount_2=18.95 paypal_quantity_2=1 paypal_shipping_2=0.00 paypal_shipping2_2=0.00 paypal_handling_2=0.00 paypal_tax_2=0.00 // Include the API fields for the billing // and shipping information here PayPal Services Implementation Guide September

140 PayPal Reply Variables APPENDIX C PDT Reply Variables if you are using Payment Data Transfer, you receive these variables from PayPal in the POST when you create a regular payment button. See "Information from PayPal: Payment Data Transfer (PDT)," page 15 for more information. Table 30 Variable tx st PayPal s PDT Reply Variables Description Transaction ID/Payment Data Transfer token. You can use the token to receive additional transaction information from PayPal. For more information, see PayPal s Merchant User Manual and Integration Guide. Status variable indicating whether the payment was successful and whether you can ship the goods. This variable will contain one of the following values: Completed: Payment is complete. Denied: You denied the payment. Failed: Payment failed. Only occurs if the payment comes from the customer's bank account. Pending: Payment is pending. amt cc cm sig Total amount of the payment. Currency code. During the button creation, CyberSource populates this field with various identifiers, and PayPal echoes the field in the PDT reply. The field contains three identifiers separated by commas. If you are using the Simple Order API, the three identifiers are the paypalbuttoncreatereply_ reconciliationid from CyberSource s reply, the requestid from CyberSource s reply, and the merchantreferencecode that you provided in the request. If you are using the SCMP API, the three identifiers are the paypal_button_create_trans_ref_no from CyberSource s reply, the request_id from CyberSource s reply, and the merchant_ref_number that you provided in the request. PayPal s signature. PayPal Services Implementation Guide September

141 Appendix C PayPal Reply Variables Reply Variables for Creating a Billing Agreement The reply variables that you receive from PayPal in the return POST after the customer goes to PayPal s site to approve a billing agreement. Table 31 PayPal s HTML Reply Variables for Creating a Billing Agreement HTML Variable first_name last_name mp_custom mp_cycle_start mp_desc mp_id mp_max mp_pay_type Description Customer's personal first name if the customer does not have a PayPal Business or Premier account. Customer's personal last name if the customer does not have a PayPal Business or Premier account. CyberSource populates this field with various identifiers, and PayPal echoes the field in the IPN message. The field contains six identifiers separated by commas. If you are using the Simple Order API, the first three identifiers are the paypalbuttoncreatereply_reconciliationid from CyberSource s reply, the requestid from CyberSource s reply, and the merchantreferencecode that you provided in the request. If you are using the SCMP API, the first three identifiers are the paypal_button_ create_trans_ref_no from CyberSource s reply, the request_id from CyberSource s reply, and the merchant_ref_number that you provided in the request. The last three identifiers are CyberSource internal tracking values. Day of the month on which the monthly billing cycle starts. Pass-through variable. Contains exactly what you provided in paypal_mp_desc when you created the button. The billing agreement identifier that you must store to process preapproved payments for the customer. The value is unique and does not change throughout the life of the billing agreement. The value is a total of 19 characters, starting with the single-character prefix B, followed by a hyphen and an alphanumeric character string. Example: B ABCDEFGH. The maximum monthly amount that the customer agreed to for the preapproved payments. Types of PayPal funding sources the customer's account is capable of using. The value none indicates that PayPal does not have a current or valid funding source possibly because the customer is waiting to verify a bank account. Some customers might be so new to using PayPal that they may not have completed their enrollment. Check for a value of mp_2005 for the HTML variable reason_code. The field can contain these values: echeck instant none PayPal Services Implementation Guide September

142 Appendix C PayPal Reply Variables Table 31 PayPal s HTML Reply Variables for Creating a Billing Agreement (Continued) HTML Variable mp_status Description The status of the billing agreement. The field will contain one of the following values: 0: The customer accepted the billing agreement 1: The customer did not accept the billing agreement mp_test_result payer_business_ name payer_ payer_id payer_status Returned if you included paypal_test_amount when you created the button. Shows the result of the test against PayPal's fraud and risk models. The field can contain one of the following values: passed failed The value passed is a reasonable assurance that the customer's account can be billed in the future. Name of the customer's business, returned only if the customer has a PayPal Business or Premier account. Customer's primary address. Customer's unique PayPal-generated identification number. Status of the customer's PayPal account. The field can contain one of the following values: verified: Customer s account is Verified unverified: Customer s account is Unverified PayPal Services Implementation Guide September

143 Appendix C PayPal Reply Variables Table 31 PayPal s HTML Reply Variables for Creating a Billing Agreement (Continued) HTML Variable reason_code Description Value indicating status of a new billing agreement that you can receive. You receive this variable when PayPal POSTs you the response after the customer goes to PayPal s site to approve the billing agreement. mp_2001: Billing agreement created. mp_2002: Billing agreement canceled by payer. mp_2003: 14-day notice that the customer's last funding source is due to expire. Note that the agreement is not cancelled when the funding source expires. Customers may still be able to pay by using their PayPal balance. mp_2004: Account is locked or restricted. mp_2005: Customer is a new PayPal member with account pending verification. mp_2006: Billing agreement canceled by PayPal. mp_2007: User canceled before completing billing agreement. Reasons for this may include: Buyer resides in a country where functionality is not offered. Buyer agreed but cancelled while adding a funding source. mp_2008: Agreement description was updated (indicates if user agreed to a new description). mp_2009: User canceled upgrade; previous agreement in effect. mp_2010: Not used. mp_2011: Customer has removed last funding source. mp_2013: Monthly maximum payment amount has changed. mp_2014: Billing agreement changed due to Preapproved Payments API call. validation_1021: Amount is required. validation_1022: mp_id is required. validation_1023: Amount is formatted incorrectly; do not use thousands separators; decimal separator must be a period; amount must not be longer than 10 characters, including the decimal separator. validation_1024: mp_id is not recognized. validation_1025: mp_pay_type is formatted incorrectly; the data type is text and must be i, e, or x (instant, echeck, or either). validation_1026: Tax is formatted incorrectly; do not use the thousands separators; decimal separator must be a period; tax must not be longer than 7 characters, including the decimal separator. validation_1027: Shipping is formatted incorrectly; do not use the thousands separators; decimal separator must be a period; shipping must not be longer than 7 characters, including the decimal separator residence_country Customer's self-declared country of residence. PayPal Services Implementation Guide September

144 Appendix C PayPal Reply Variables IPN Variables for Regular Payments IPN messages contain only alphanumeric characters. Unless otherwise specified, the maximum field length for each IPN variable returned is 127 characters. Special characters are translated into URL encoding format. For example, the colon : in is translated to %3A in the IPN message. A sample IPN message looks like this (line breaks have been added for clarity): status=completed& address_zip=47405& mc_shipping=0.00& mc_handling=0.00& first_name=larry& mc_fee=1.49& address_name=larry+smith& notify_version=1.6& custom= %2c & payer_status=verified& business=jdoe%40companyabc.com& address_country=united+states& num_cart_items=1& mc_handling1=0.00& address_city=bloomington& payer_ =lsmith%40customer.com& verify_sign=a0sz-o1clawjfjd5.kpi9bjkjyluaiqazfebut8pdpm2vjihpr9ahe-i& mc_shipping1=0.00& tax1=0.00& txn_id=1lm18508ku470513m& payment_type=instant& last_name=smith& receiver_ =jdoe%companyabc.com& item_name1=book& address_state=in& payment_fee=1.49& quantity1=1& receiver_id=8czzhszrquhua&t xn_type=cart& mc_currency=usd& mc_gross_1=41.00& test_ipn=1& payment_gross=41.00 PayPal Services Implementation Guide September

145 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments Variable Description Max Length address_city City of customer s street address. 40 address_country Country of customer s address. 64 address_name Name used with address (included when the customer provides a gift address). address_state State of customer s address. 40 address_status Whether the address is confirmed. This field will contain one of the following values: confirmed: Customer provided a confirmed address unconfirmed: Customer provided an unconfirmed address address_street Customer s street address. 200 address_zip Postal code of customer s address. 20 business custom exchange_rate Merchant s address or account ID. Equivalent to receiver_ if payment is sent to primary account, and essentially an echo of the business variable that was passed to PayPal in the button CyberSource populates this field with various identifiers, and PayPal echoes the field in the IPN message. The field contains six identifiers separated by commas. If you are using the Simple Order API, the first three identifiers are the paypalbuttoncreatereply_reconciliationid from CyberSource s reply, the requestid from CyberSource s reply, and the merchantreferencecode that you provided in the request. If you are using the SCMP API, the first three identifiers are the paypal_button_create_trans_ref_no from CyberSource s reply, the request_id from CyberSource s reply, and the merchant_ref_ number that you provided in the request. The last three identifiers are CyberSource internal tracking values. Exchange rate used if a currency conversion occurred. first_name Customer s first name. 64 invoice item_name and item_name# CyberSource populates this field with an identifier, and PayPal echoes the field in the IPN message. If you use the Simple Order API, the identifier in CyberSource s reply is paypalbuttoncreatereply_reconciliationid. If you use the SCMP API, the identifier in CyberSource s reply is paypal_button_create_trans_ref_no. Item name passed by you or entered by the customer (if not passed by you). If this is a shopping cart transaction, PayPal appends the number of the item (item_name1, and so on) PayPal Services Implementation Guide September

146 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments (Continued) Variable Description Max Length item_number and item_number# Pass-through variable for you to track purchases that is passed back to you at completion of payment. Not returned if not included in the button. last_name Customer s last name. 64 mc_currency mc_fee mc_gross and mc_gross_# mc_handling and mc_handling# mc_shipping and mc_shipping# Currency of the payment. The value will be USD, CAD, EUR, GBP, or JPY. Transaction fee for the payment. The mc_gross minus mc_fee will equal the amount deposited into the receiver_ account. Equivalent to payment_fee for USD payments. If this amount is negative, it indicates a refund or reversal, and the refund or reversal can be for the full or partial amount of the original transaction. Full amount of the customer s payment before transaction fee is subtracted. Equivalent to payment_gross for USD payments. If this amount is negative, it indicates a refund or reversal, and the refund or reversal can be for the full or partial amount of the original transaction. For a shopping cart transaction, PayPal appends the number of the item (mc_gross_1, and so on). The sum of all the mc_gross_# values should total mc_gross. Total handling amount associated with the transaction. For a shopping cart transaction, PayPal appends the number of the item (mc_handling1, and so on). For a shopping cart transaction, the handling_cart cart-wide variable is also included in the mc_handling variable; for this reason, the sum of the mc_handling# values may not be equal to mc_handling. Total shipping amount associated with the transaction. For a shopping cart transaction, this is the combined total of the paypal_shipping and paypal_shipping2 API fields that you pass to CyberSource, where # is the number of the item. The mc_ shipping# is only returned when you apply a shipping amount for a specific item. Because profile shipping may apply, the sum of the mc_shipping# values may not equal mc_shipping. notify_version Version of the IPN message. Example: 1.6 num_cart_items option_name1 and option_name1_# For a shopping cart transaction, number of items in the cart. Option 1 name as requested by you. For a shopping cart transaction, PayPal appends the number of the item (option_name1_1, and so on) PayPal Services Implementation Guide September

147 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments (Continued) Variable Description Max Length option_name2 and option_name2_# option_selection1 and option_selection1_# option_selection2 and option_selection2_# parent_txn_id Option 2 name as requested by you. For a shopping cart transaction, PayPal appends the number of the item (option_name2_1, and so on). Option 1 choice as entered by the customer. For a shopping cart transaction, PayPal appends the number of the item (option_selection1_1, and so on). Option 2 choice as entered by the customer. For a shopping cart transaction, PayPal appends the number of the item (option_selection2_1, and so on). In the case of a refund, reversal, or canceled reversal, this variable contains the txn_id of the original transaction, while txn_id contains a new ID for the new transaction. See the description of txn_id in this table. payer_business_name Customer s company name. 127 payer_ Customer s primary address. Use this to provide any credits. payer_id PayPal s unique customer ID. 13 payer_status Whether the customer has a verified account. This field will contain one of the following values: Verified: Customer has a Verified PayPal account Unverified: Customer has an Unverified PayPal account payment_date payment_fee payment_gross PayPal s time stamp. Example: 18:30:30 Jan 1, 2000 PST. USD transaction fee for the payment. The payment_gross minus payment_fee will equal the amount deposited into the receiver_ account. Will be empty for non-usd payments. This is a legacy field replaced by mc_fee. If this amount is negative, it indicates a refund or reversal, and the refund or reversal can be for the full or partial amount of the original transaction. Full USD amount of the customer s payment before the transaction fee is subtracted. Will be empty for non-usd payments. This is a legacy field replaced by mc_gross. If this amount is negative, it indicates a refund or reversal, and the refund or reversal can be for the full or partial amount of the original transaction. PayPal Services Implementation Guide September

148 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments (Continued) Variable Description Max Length payment_status Status of the payment. This field can contain one of the following values: Canceled-Reversal: Reversal has been canceled. For example, you won a dispute with the customer and the funds for the reversed transaction have been returned to you. Completed: If referring to an initial purchase, this means the payment has been completed and the funds have successfully been added to your account balance. Denied: You denied the payment. This happens only if the payment was previously pending due to one of the reasons specified by the pending_reason variable. See below. Failed: Payment has failed. This happens only if the payment was attempted from the customer s bank account. Pending: See the pending_reason variable for the reason why the payment is pending. You will receive another IPN when the status changes to Completed, Failed, or Denied. Refunded: You refunded the payment. payment_type Reversed: Payment was reversed due to a chargeback or other type of reversal. The funds have been debited from your account balanced and returned to the customer. Look for the reason for the reversal in the reason_code variable. See below. Indicates whether the payment is instant or delayed. This field will contain one of the following values: echeck: Electronic check instant: Credit card, PayPal balance, or Instant Transfer PayPal Services Implementation Guide September

149 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments (Continued) Variable Description Max Length pending_reason quantity and quantity# reason_code Reason if payment_status=pending. This field contains one of these values: address: Customer did not include a confirmed shipping address and you have your Payment Receiving Preferences set to manually accept or deny each of these payments. echeck: Electronic check has not cleared yet. intl: You hold a non-u.s. account and do not have a withdrawal method. You must manually accept or deny this payment from your PayPal 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 the payment. You must manually accept or deny the payment. other: Payment is pending for a reason other than the other reasons listed here. Contact PayPal Customer Service. unilateral: The payment was made to an address that is not yet registered or confirmed. upgrade: Payment was made via credit card and you must upgrade your account to Business or Premier status to receive the funds. You could also get this status because you have reached the monthly limit for transactions on your account. verify: You are not yet verified. You must verify your account before you can accept the payment. Quantity passed by you or entered by the customer (if not passed by you). For a shopping cart transaction, PayPal appends the number of the item (quantity1, and so on). Reason for a refund or reversal. This field is returned only if payment_status=reversed or Refunded. This field contains one of these values: buyer_complaint: A reversal has occurred because of a complaint from your customer about the transaction. chargeback: A reversal has occurred because of a chargeback by the customer. guarantee: A reversal has occurred because the customer triggered a money-back guarantee. refund: A reversal has occurred because you have given the customer a refund. other: A reversal has occurred for a reason other than those stated above. 127 PayPal Services Implementation Guide September

150 Appendix C PayPal Reply Variables Table 32 IPN Variables for Regular Payments (Continued) Variable Description Max Length receiver_ Merchant s primary address. If the payment is sent to a nonprimary address on your PayPal account, the receiver_ will still be your primary . receiver_id Merchant s unique account ID (same as the referral ID). 13 settle_amount settle_currency tax and tax# Amount deposited into the account s primary balance after a currency conversion either by automatic conversion (through your Payment Receiving Preferences) or manual conversion (through manually accepting a payment). Currency of settle_amount. Amount of tax charged on the payment. For a shopping cart transaction, PayPal appends the number of the item (tax1, and so on). The tax# is only included if there was a specific tax amount applied to a particular shopping cart item. Because profile-based tax may apply to other items in the cart, the sum of tax# might not total to tax. txn_id PayPal s unique transaction ID. 17 txn_type verify_sign Type of transaction. This field will contain one of the following values: cart: Payment was sent by the customer via the PayPal Shopping Cart. send_money: Payment was sent by your customer from the PayPal Web site using the Send Money tab. web_accept: Payment was sent by your customer via Buy Now buttons, Donations, or Smart Logos. Encrypted string used to validate the authenticity of the transaction. 127 PayPal Services Implementation Guide September

151 Appendix C PayPal Reply Variables IPN Variables for Preapproved Payments When creating or updating a billing agreement, you receive these variables: mp_pay_type mp_test_result (if you sent mp_test_amount when creating the button) For all other events related to a billing agreement or preapproved payment, you receive these IPN variables: mp_id mp_currency payer_status mp_desc first_name payer_business_name (if a business account) mp_max last_name residence_country mp_status payer_ reason_code mp_custom payer_id See "Reply Variables for Creating a Billing Agreement," page 141 for descriptions of these variables. PayPal Services Implementation Guide September

152 Product Codes APPENDIX D This table lists the values you can use for the product code. For the Simple Order API, use the item_#_productcode request field to specify the product code. For the SCMP API, use the product_code offer-level field. Table 33 Product Codes Product Code adult_content coupon default electronic_good electronic_software gift_certificate handling_only service shipping_and_handling shipping_only subscription Definition Adult content. Coupon applied to the entire order. Default value for the product code. CyberSource uses default when a request message does not include a value for the product code. Electronic product other than software. Software distributed electronically rather than on disks or other media. Gift certificate. Fee that you charge your customer to cover your administrative selling costs. Service that you perform for your customer. The shipping portion is the charge for shipping the product to your customer. The handling portion is the fee you charge your customer to cover your administrative selling costs. Charge for transporting tangible personal property from your location to your customer. You must maintain documentation that clearly establishes the location where the title to the property passed from you to your customer. Subscription to a web site or other content. PayPal Services Implementation Guide September

153 INDEX Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z A account configuration CyberSource 34 PayPal 23 API access 29 Auto Return 15, 32 automatic funds transfer 33 B billing agreements canceling 12 SCMP API 99 Simple Order API 63 described 11 identifier 11 IPN events 17 IPN variables 151 reason codes 143 reply POST SCMP API 77 Simple Order API 42 variables 15, 141 updating 12 SCMP API 99 Simple Order API 63 business 38 business account 8 button creation 9 billing agreement 11 SCMP API 72 shopping cart 108 Simple Order API 37 Buy Now buttons. See regular payments Buyer Complaint Process 21 C cancel URL 9, 34 canceling billing agreements 12 SCMP API 99 Simple Order API 63 chargebacks 21 cmd 38 configuring your account CyberSource 34 PayPal 23 confirmed address 21 cookies, enabling 35 creating buttons 9 billing agreements 11 SCMP API 72 shopping carts 108 Simple Order API 37 credit card statement name 25 credits described 13 SCMP API 102, 103 Simple Order API 67 currencies, using multiple 33 custom 38 CyberSource reports 17 D date and time format 55 SCMP API 91 PayPal Services Implementation Guide September

154 Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z E electronic checks 24 notifications 10, 24 encrypted button 41 SCMP API 76 examples 110 SCMP API 128 F fraud test 151 fulfilling orders 15 funding sources 8 funds transfer 33 G GMT 55 H Hosted Order Page Business Center settings 35 PayPal settings 24 I ics_paypal_button_create 72 ics_paypal_credit 102 ics_paypal_preapproved_payment 92 ics_paypal_preapproved_update 99 ics_rcode reply field 90 ics_rflag reply field 90 ics_rmsg reply field 90 ics_tax 72, 92 invoice 38 IPN described 16 message forwarding 34 notification URL 26 variables 144 M MIP. See billing agreements or preapproved payments mp_id 11, 42, 141 SCMP API 77 mp_test_result 151 multiple currencies 33 N notify_url 38 O order fulfillment 15 order tracking 14 P Payment Batch Summary Report 18 Payment Data Transfer. See PDT Payment Events Report 12, 13, 17 Payment Invoice Summary Report 18 Payment Submission Detail Report 18 payments. See regular payments or preapproved payments PayPal Account, opening and configuring 23 PayPal business account 8 paypal_business 38 paypalbuttoncreateservice 37 paypal_cancel_return 34 paypal_cmd 38 paypalcreditservice 67 paypal_custom 38 paypal_invoice 38 paypal_notify_url 38 paypalpreapprovedpaymentservice 56 paypalpreapprovedupdateservice 63 paypal_return 10, 32, 34 PayPal Services Implementation Guide September

155 Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z PDT 42 described 15 reply variables 140 SCMP API 77 POST from PayPal 42 SCMP API 77 preapproved payments 9 described 11 IPN events 17 IPN variables 151 SCMP API 92 Simple Order API 56 product codes 152 R reason codes 70 PayPal 143 reconciliation IDs 14 reconciliation with settlement file 33 refunds described 13 SCMP API 102 Simple Order API 67 regular payments API fields SCMP API 78 described 9 IPN events 16 IPN variables 144 shipping address 39 SCMP API 74 shipping and handling 39 SCMP API 74 specifying tax 40 SCMP API 75 variables in the button 37 SCMP API 72 reports 17 request ID and credits 103 request IDs 14 and credits 67 S sample code 110 SCMP API 128 sandbox 71, 107 SCMP API requesting services with 72 Security Center 22 Seller Protection Plan 21, 36 settings 24 settlement file 18, 33 shipping address 36, 39 SCMP API 74 shipping and handling 39 SCMP API 74 shipping goods 15 shopping cart button 108 signing up CyberSource 34 PayPal 23 success URL 9, 10, 32 T tax 40 SCMP API 72, 75, 92 Simple Order API 37, 56 testing 71, 107 time format 55 SCMP API 91 transaction reference numbers 14 tx token 140 PayPal Services Implementation Guide September

156 Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z U unencrypted button 41 SCMP API 76 updating billing agreements 12 SCMP API 99 Simple Order API 63 UTC 55 PayPal Services Implementation Guide September