CyberSource PayPal Services Implementation Guide ®

Transcription

CyberSource PayPal® Services
Implementation Guide
Simple Order API
SCMP API
August 2013
CyberSource Corporation HQ | P.O. Box 8999 | San Francisco, CA 94128-8999 | Phone: 800-530-9095
CyberSource Contact Information
For general information about our company, products, and services, go to
http://www.cybersource.com.
For sales questions about any CyberSource Service, email [email protected] or
call 650-432-7350 or 888-330-2300 (toll free in the United States).
For support information about any CyberSource Service, visit the Support Center at
http://www.cybersource.com/support.
Copyright
© 2013 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
252.227-7013 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 52.227-19 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
CONTENTS
Contents
Recent Revisions to This Document
Chapter 1
Introduction
7
8
About PayPal Payments
8
PayPal Payments 8
Payments Through the Hosted Order Page
Payments Through an API 9
Regular Payments 9
Preapproved Payments 11
Billing Agreements 12
PayPal Credits
8
13
Order Tracking with an API 14
Reconciliation IDs and Transaction Reference Numbers
Request IDs 14
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 Email Messages 19
CyberSource Email Messages 19
Chargebacks
21
Additional Documentation 22
PayPal References 22
CyberSource Guides 22
PayPal Services Implementation Guide | August 2013
3
Contents
Chapter 2
Setting Up Your System
23
Opening and Configuring Your PayPal Account 23
Settings for Hosted Order Page and API 24
Disabling Email 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
All Merchants 35
Chapter 3
35
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
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
Request Fields 57
Reply Fields 60
39
56
Canceling or Updating a Billing Agreement
Request Fields 64
Reply Fields 65
63
Processing a Credit 67
Request Fields 67
Reply Fields 69
Reason Codes
Testing
70
71
4
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
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
Reply Fields 95
Reply Flags 99
74
92
Canceling or Updating a Billing Agreement
Reply Fields 100
Reply Flags 102
99
Reply Fields 105
Reply Flags 106
Testing
Chapter 5
107
Creating a Shopping Cart Button
Appendix A Examples for the Simple Order API
108
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
Creating a Shopping Cart Button 117
5
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
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
134
Updating a Billing Agreement
Processing a Credit
136
138
Appendix C PayPal Reply Variables
PDT Reply Variables
139
140
140
Reply Variables for Creating a Billing Agreement
IPN Variables for Regular Payments
144
IPN Variables for Preapproved Payments
Appendix D Product Codes
Index
141
151
152
153
6
REVISIONS
Recent Revisions to This
Document
Release
Changes
August 2013
Removed incorrect information about Customer Support.
Updated the information about request tokens.
September 2012
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:
May 2010

Production: paypal_cybersource_api1.cybersource.com

Testing: cybersource_paypal_api1.cybersource.com
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.
7
CHAPTER
Introduction
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 www.paypal.com.
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 email address, the
amount of the transaction, and the currency.
8
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 email receipt for the order. See the samples in "CyberSource
Email 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.
9
Chapter 1
5
Introduction
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 email notification of the payment (you can turn this off if you do
not want to get the emails).

PayPal sends the customer an email receipt for the payment.

If you are using the Hosted Order Page, CyberSource sends to you and to the
customer the email receipts that you configured.
10
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 email 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.
11
Chapter 1
Introduction
After the customer accepts the billing agreement:

PayPal sends the customer an email notification for the new billing agreement.

billing agreement creation. See "Information from PayPal: Instant Payment
Notification (IPN)," page 16.



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 email notification of the payment

preapproved payment. See "Information from PayPal: Instant Payment Notification
(IPN)," page 16.



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:

cancellation or update. See "Information from PayPal: Instant Payment Notification
(IPN)," page 16.



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
12
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:

credit. See "Information from PayPal: Instant Payment Notification (IPN)," page 16.



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.
13
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
Field Names
Button create
Simple Order API: payPalButtonCreateReply_reconciliationID
SCMP API: paypal_button_create_trans_ref_no
Preapproved payment
Simple Order API: payPalPreapprovedPaymentReply_reconciliationID
SCMP API: paypal_preapproved_payment_trans_ref_no
Preapproved update
Simple Order API: payPalPreapprovedUpdateReply_reconciliationID
SCMP API: paypal_preapproved_update_trans_ref_no
Credit
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
14
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 on 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.
15
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.
16
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.
17
Chapter 1
Note
Introduction
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.
18
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 Email Messages
You automatically receive email notifications for any successful payments, canceled
payments, and pending payments. You can turn off these emails by disabling them in your
PayPal profile. For more information, see "Disabling Email Notifications," page 24.
CyberSource Email 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=1483085059980167904065
orderNumber=1148408942800
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=1484089639110167904065
decision=ACCEPT
reasonCode=100
paymentOption=paypal
orderPage_transactionType=authorization
19
Chapter 1

Introduction
Merchant’s Purchase Confirmation
Sample Header
Purchase Description
Payment Details
Order Number:
Subtotal:
Tax:
Total:
1148408942800
9.00
0.00
9.00
For Support, contact:
Your Merchant
800-555-1212
[email protected]
Order Details
Payment Type: paypal
Customer ID:
Billing Address:
John Doe
1111 Sample Avenue
Your Town, CA 99999
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!
20
Chapter 1

Introduction
Customer’s Receipt
Sample Header
Purchase Description
Payment Details
Order Number:
Subtotal:
Tax:
Total:
1148408942800
9.00
0.00
9.00
For Support, contact:
Your Merchant
800-555-1212
[email protected]
Order Details
Payment Type: paypal
Customer ID:
Billing Address:
John Doe
1111 Sample Avenue
Your Town, CA 99999
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.
21
Chapter 1
Introduction
For more information about these services, contact your PayPal Account Manager, or visit
PayPal’s Security Center (go to www.paypal.com 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.
22
CHAPTER
2
Opening and Configuring Your PayPal
Account
If you do not already have a PayPal business account, go to www.paypal.com 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
www.paypal.com.
23
Chapter 2
Settings for Hosted Order Page and API
Disabling Email Notifications
If you do not want to receive an email message every time a customer pays with PayPal at
your store, you can turn off email 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.”
24
Chapter 2
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.
PayPal * is appended at the beginning of the credit card statement name. For
example, YourCompany is included as PayPal *YourCompany.
Note
To set the credit card statement name, go to the “Payment Receiving Preferences” page.
See the screen in "Disabling Electronic Checks," page 24.
25
Chapter 2
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.
26
Chapter 2
Step 2
Click Edit.
Step 3
Check the box and enter one of these URLs:

For CyberSource’s test environment: https://paypaltest.ic3.com/ipn

For CyberSource’s production environment: https://paypal.ic3.com/ipn
27
Chapter 2
Step 4
Click Save.
You are ready to proceed to the next section.
28
Chapter 2
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.
29
Chapter 2
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.
30
Chapter 2
Step 5
Select the permissions circled in red in the following figure and then click Add.
31
Chapter 2
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.
32
Chapter 2
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.
33
Chapter 2
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.
34
Chapter 2
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
In the Business Center, go to Settings > HOP Settings.
b
Scroll to the Payment Types subsection.
c
Check the box for PayPal.
You can choose PayPal as sole form of payment or any of the other forms
available.
d
Enter your PayPal login ID.
e
If you use the Hosted Order Page, leave this field blank.
f
Complete the other configuration fields as necessary for your Hosted Order
Page implementation.
You can begin processing PayPal payments with the Hosted Order Page.
g
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.
35
Chapter 2
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.
36
CHAPTER
Requesting Services with
the Simple Order API
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
37
Chapter 3
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.
38
Chapter 3
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 www.paypal.com 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.
39
Chapter 3
Table 2
Methods for Specifying Shipping and Handling Charges
Method
Description
CyberSource:
Using a total freight
amount
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.
CyberSource:
Using an item for the
freight amount
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.
PayPal:
Using a profile-based
freight amount
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.
PayPal:
Overriding the profilebased freight amount
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.
40
Chapter 3
Table 3
Methods for Specifying an Order’s Tax
Method
Description
CyberSource:
Using a total tax amount
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.
CyberSource:
Using an item-level tax
amount
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.
PayPal:
Using a profile-based tax
amount
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.
PayPal:
Overriding the profile-based
tax amount
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>

Click PayPal Checkout to proceed with your PayPal payment.
This will take you to the PayPal login page.

%s
</body></html>
41
Chapter 3
The encrypted version of the button looks similar to this:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post"><input
type="image" src="https://https://www.paypal.com/en_US/i/btn/x-click-but23.gif"
border="0" name="submit"><input type="hidden" name="cmd" value="_s-xclick"><input
type="hidden" name="encrypted" value="
-----BEGIN PKCS7----MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB
AgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQEBAQUABIGAg0SFsADkAz5l03qK8w
e8z3zt86F9IZB8q8J+oCSjmBWgrZdh+VKHgPL2SKuRGrifwXDCGFOJonjYK5EKExeSCmR/eZRUwzIpUmnKAY/
r7Hqzd/e1IslJuFZ9/iKQO2hK/wRq5VYIL22MGn0fY8GZ6CBmM76ceYojOe/
XmlpUOLjANQnx2MVMI85hhpMAcaM-----END PKCS7-----"</form>
The encrypted information in the above example has been shortened for
illustration. The actual length of the information is about 2000-3000 characters.
Note
The unencrypted version of the button looks similar to this:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post"><input
type="image" src="https://https://www.paypal.com/en_US/i/btn/x-clickbut23.gif" 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="http://cancel.example.com"><input type="hidden" name="undefined_quantity"
value="1"><input type="hidden" name="quantity" value="5"><input type="hidden"
name="return" value="http://success.example.com"><input 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="http://example.com/
ipn"><input type="hidden" name="invoice" value="0000028962"><input type="hidden"
name="custom" value="0000028962,1141312425560167905065,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.
42
Chapter 3
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
Country of the billing address. Use the twocharacter ISO codes. See the Support Center
for a list of codes.
Both
Required
String (2)
billTo_email
Customer’s email address, including the full
domain name (for example,
[email protected]).
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
Postal code for the billing address. The postal
code must consist of 5 to 9 digits.
Both
Required if
country is
U.S. or
Canada
String (10)
Both
Required if
country is
U.S. or
Canada
String (2)
If the billing country is the U.S., the 9-digit
postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If the billing country is Canada, the 6-digit
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
billTo_state
State or province of the billing address. Use
the two-character codes. See the Support
Center for a list of valid codes.
(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.
43
Chapter 3
Table 4
Button Create Request Fields (Continued)
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
item_#_
productCode
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.
Regular
payment
Optional
String (30)
item_#_
productName
Product’s name. This information is not
displayed in the button but is displayed on the
transaction details screen in the Business
Center.
Regular
payment
See
description
String (30)
Regular
payment
See
description
String (30)
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.
item_#_productSKU
Product’s identifier code. This information is
not displayed in the button but is displayed in
the transaction details screen in the Business
Center.
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.
44
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
item_#_quantity
Quantity of the product being purchased. The
default value is 1.
Regular
payment
See
description
Integer
(10)
Regular
payment
Optional
String (15)
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.
item_#_taxAmount
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.
45
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
item_#_unitPrice
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.
Regular
payment
See
description
String (15)
Regular
payment
Optional
String (26)
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.
linkToRequest
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.
merchantID
Your CyberSource merchant ID. Use the
same merchantID for evaluation, testing, and
production.
Both
Required
String (30)
merchantReference
Code
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.
Both
Required
String (50)
paypal_amount
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.
Neither
See
description
N/A
46
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_cancel_
return
URL of the Web page to show the customer if
the customer cancels the regular PayPal
payment. Example: http://
cancel.example.com.
Regular
payment
Required
String
(255)
paypal_customer_
email
domain name (for example,
[email protected]).
Both
Optional
String
(255)
paypal_handling
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.
Regular
payment
Optional
String (15)
Regular
payment
Optional
String
(127)
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
paypal_item_name
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.
47
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_item_
number
This becomes the value for the item_
number variable in the button. It is not
Regular
payment
Optional
String
(127)
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.
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.
paypal_lc
Locale (language) for the billing agreement
pages. Use the two-character ISO country
codes.
Billing
agreement
Optional
String (2)
paypal_mp_cycle_
start
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.
Billing
agreement
Optional
Integer (2)
paypal_mp_desc
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 email confirmation from
PayPal when a billing agreement is created or
updated, in the transaction detail history for
each preapproved payment, and in the email
confirmation from PayPal when a
preapproved payment is processed.
Billing
agreement
Optional
String (no
length
limit)
48
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_mp_error
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:
Billing
agreement
Optional
Integer (1)

0 (default): No, do not show the error

1: Yes, show the error
paypal_mp_max
Maximum amount that you can withdraw from
the customer's account for a preapproved
payment.
Billing
agreement
Required
String (15)
paypal_mp_max_
edit
Whether the customer can edit the monthly
maximum billing amount (paypal_mp_max).
Use one of the following values:
Billing
agreement
Optional
Integer (1)

0 (default): No, the customer cannot edit
the value

1: Yes, the customer can edit the value
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)
Billing
agreement
Optional
String (15)
paypal_mp_test_
amount

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.
49
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_quantity
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.
Regular
payment
See
description
Integer
(no limit)
Regular
payment
Required
String
(255)
Optional
Integer (1)
API field (item_#_quantity), the quantity
variable in the button is NOT populated based
on CyberSource’s item_#_quantity field.
paypal_return
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: http://
success.example.com
Billing
agreement
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.
paypal_rm
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
Billing
agreement
50
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_shipping
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.
Regular
payment
Optional
String (15)
Regular
payment
Optional
String (15)
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.
items in the order (paypal_quantity).The
paypal_shipping2
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
51
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
paypal_tax
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.
Regular
payment
Optional
String (15)
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.
paypal_undefined_
quantity
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.
Regular
payment
Optional
Integer (1)
payPalButtonCreate
Service_buttonType
Type of button to create. Use one of the
following values:
All
Required
String (30)
Both
Required
String (5)

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
payPalButtonCreate
Service_run
Set this field to true to request
payPalButtonCreateService.
52
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
purchaseTotals_
currency
This becomes the value for the currency_
code variable in the button. This is the
Regular
payment
Required
String (5)
Regular
payment
Optional
String (15)
currency used for the order. PayPal currently
accepts orders that use USD, CAD, EUR, GBP,
or JPY only.
purchaseTotals_
freightAmount
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.
purchaseTotals_
grandTotalAmount
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
Regular
payment
See
description
String (15)
purchaseTotals_
taxAmount
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.
Regular
payment
Optional
String (15)
This value overrides any profile-based tax
charge you have set. See "Specifying Tax for
a Regular Payment Button," page 40 for more
details.
shipTo_city
City to which to ship the product.
Regular
payment
Optional (1, 2)
String (50)
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
Optional (2)
String (2)
shipTo_firstName
First name of person receiving the product.
Regular
payment
Optional (2)
String (60)
shipTo_lastName
Last name of person receiving the product.
Regular
payment
Optional (2)
String (60)
53
Chapter 3
Table 4
Request Field
Description
Use With
Button
Required/
Optional
Data
Type &
Length
shipTo_postalCode
Postal code for the shipping address. The
postal code must consist of 5 to 9 digits.
Regular
payment
Optional (2, 3)
String (10)
If the shipping country is the U.S., the 9-digit
Example: 12345-6789
If the shipping country is Canada, the 6-digit
Example: A1B 2C3
shipTo_
shippingMethod
Shipping method for the product. For
example, FEDEX.
Regular
payment
Optional
String (10)
shipTo_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
Optional (2, 3)
String (2)
shipTo_street1
First line of the address to which to ship the
product.
Regular
payment
Optional (1, 2)
String (60)
shipTo_street2
Second line of the address to which to ship
the product.
Regular
payment
Optional (2)
String (60)
54
Chapter 3
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
Summarizes the result of the overall request. The field can contain
String (6)

ACCEPT

ERROR

REJECT
invalidField_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
String
(100)
merchantReferenceCode
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)
missingField_0...N
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
String
(100)
payPalButtonCreateReply_
buttonType
Type of button created. This field will contain one of the following
values:
String (30)

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.
encryptedFormData
Encrypted version of the button.
String (no
length
limit)
reasonCode
A numeric value corresponding to the result of the button creation
request. See "Reason Codes," page 70 for a list of possible values.
Integer (5)
reconciliationID
Reference number for the transaction that you use to reconcile your
transactions.
String (60)
requestDateTime
Time of the button creation request. The format is YYYY-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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 (20)
55
Chapter 3
Table 5
Reply Fields for Button Create (Continued)
Reply Field
Description
Data
Type &
Length
unencryptedFormData
Unencrypted version of the button.
String (no
length
limit)
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)
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.
56
Chapter 3
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
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_email
Customer’s email address, including the full domain
name (for example, [email protected]).
Optional
String
(255)
billTo_firstName
Required
String (60)
billTo_lastName
Required
String (60)
billTo_postalCode
Postal code for the billing address. The postal code
must consist of 5 to 9 digits.
Required if
country is
U.S. or
Canada
String (10)
If the billing country is the U.S., the 9-digit postal
code must follow this format:
Example: 12345-6789
If the billing country is Canada, the 6-digit postal code
must follow this format:
Example: A1B 2C3
billTo_state
State or province of the billing address. Use the
two-character codes. See the Support Center for a
list of valid codes.
Required if
country is
U.S. or
Canada
String (2)
item_#_productCode
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.
Optional
String (30)
item_#_productName
Product’s name. Required if item_#_productCode is
NOT default, stored_value, or one of the
See
description
String (30)
item_#_productSKU
Product’s identifier code. Required if item_#_
productCode is NOT default, stored_value,
or one of the values related to shipping and/or
handling.
See
description
String (30)
57
Chapter 3
Table 6
Preapproved Payment Request Fields (Continued)
Request Field
Description
Required
/
Optional
Data
Type &
Length
item_#_quantity
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.
See
description
Integer
(10)
item_#_taxAmount
Total tax to apply to the product. This value cannot be
negative.
Optional
String (15)
See
description
String (15)
Optional
String (26)
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.
item_#_unitPrice
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.
linkToRequest
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
merchantID
Your CyberSource merchant ID. Use the same
merchantID for evaluation, testing, and production.
Required
String (30)
Merchant-generated order reference or tracking
number. See the information about order tracking in
Required
String (50)
paypal_customer_email
name (for example, [email protected]).
Optional
String
(255)
paypal_email_subject
Subject line of the confirmation email that will be sent
to the customer.
Optional
String (no
length
limit)
paypal_item_name
Name of the purchased item.
Optional
String (no
length
limit)
58
Chapter 3
Table 6
Preapproved Payment Request Fields (Continued)
Request Field
Description
Required
/
Optional
Data
Type &
Length
paypal_item_number
Reference number of the purchased item.
Optional
String (no
length
limit)
paypal_memo
Text entered by the customer in the Note field during
enrollment.
Optional
String (no
length
limit)
paypal_payment_type
The type of PayPal payment funding source to use.
Optional
String (11)

Any (default): Any payment type is acceptable

EcheckOnly: eCheck

InstantOnly: Instant only
Make sure to provide the value exactly as shown
above.
payPalPreapproved
PaymentService_mpID
Billing agreement identifier (the mp_id).
Required
String (19)
payPalPreapproved
PaymentService_run
Set to true to request
payPalPreapprovedPaymentService.
Required
String (5)
purchaseTotals_currency
Currency used for the order. PayPal currently
accepts orders that use USD, CAD, EUR, GBP, or
JPY only.
Required
String (5)
purchaseTotals_
grandTotalAmount
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.
See
description
String (15)
59
Chapter 3
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:
String (6)

ACCEPT

ERROR

REJECT
invalidField_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.
String
(100)
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)
missingField_0...N
Required fields that were missing from the request. These
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)
payPalPreapproved
PaymentReply_desc
Value of the paypal_mp_desc field you provided when
creating the billing agreement button.
String (no
length limit)
payPalPreapproved
PaymentReply_exchangeRate
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 (15)
payPalPreapproved
PaymentReply_feeAmount
PayPal fee amount charged for the transaction.
String (15)
payPalPreapproved
PaymentReply_mpMax
Monthly maximum payment amount.
String (15)
payPalPreapproved
PaymentReply_mpStatus
Current status of the billing agreement. This field will
String (9)

Active

Canceled
60
Chapter 3
Table 7
Preapproved Payment Reply Fields (Continued)
Reply Field
Description
Data
Type &
Length
payPalPreapproved
PaymentReply_payer
Customer's PayPal account identifier (customer's email
address).
String (no
length limit)
payPalPreapproved
PaymentReply_payerBusiness
Customer's business name if the customer has a PayPal
Business or Premier account.
String (no
length limit)
payPalPreapproved
PaymentReply_payerCountry
Customer's country of residence.
String (no
length limit)
payPalPreapproved
PaymentReply_payerID
PayPal-generated unique customer ID.
String (no
length limit)
payPalPreapproved
PaymentReply_payerName
Customer's name.
String (no
length limit)
payPalPreapproved
PaymentReply_payerStatus
Status of the customer's email address. This field will
String (10)

verified: Customer’s PayPal account is Verified

unverified: Customer’s PayPal account is
Unverified
payPalPreapproved
PaymentReply_paymentDate
PayPal's timestamp for the payment. Example:
String (20)
18:30:30 Jan 1, 2000 PST.
payPalPreapproved
PaymentReply_
paymentGrossAmount
The final amount charged including any shipping or taxes
from your PayPal profile.
String (15)
payPalPreapproved
PaymentReply_paymentStatus
Status of the preapproved payment. This field will contain
String (9)

Completed

Pending (see reasons in
payPalPreapprovedPaymentReply_pendingReason
below)
payPalPreapproved
PaymentReply_paymentType

Failed

Retry
Indicates whether the payment is instant or delayed. This
field will contain one of the following values:

echeck

instant
String (7)
61
Chapter 3
Table 7
Reply Field
Description
Data
Type &
Length
payPalPreapproved
PaymentReply_pendingReason
Reason if payPalPreapprovedPaymentReply_
paymentStatus=Pending. This field will contain one of
these values:
String (14)

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 email
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.
payPalPreapproved
PaymentReply_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.
Integer (5)
payPalPreapproved
PaymentReply_reconciliationID
Reference number for the transaction that you use to
reconcile your transactions.
String (60)
payPalPreapproved
PaymentReply_requestDateTime
Time of the preapproved payment request. The format is
YYYY-MM-DDThh:mm:ssZ. For example, 2003-0811T22: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 (20)
payPalPreapproved
PaymentReply_settleAmount
Amount deposited in your PayPal account after a currency
conversion.
String (15)
payPalPreapproved
PaymentReply_taxAmount
Tax charged on the transaction.
String (15)
62
Chapter 3
Table 7
Reply Field
Description
Data
Type &
Length
payPalPreapproved
PaymentReply_transactionID
PayPal's unique transaction ID for the payment.
String (no
length limit)
payPalPreapproved
PaymentReply_transactionType
Type of PayPal payment. This field will contain the value
mercht-pmt.
reasonCode
Numeric value corresponding to the result of the overall
request. See "Reason Codes," page 70 for a list of
possible values.
Integer (5)
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)
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.
63
Chapter 3
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
Data
Type &
Length
merchantID
Your CyberSource merchant ID. Use
the same merchantID for evaluation,
testing, and production.
Required
String (30)
Merchant-generated order reference
or tracking number. See the
information about order tracking in
Getting Started with CyberSource
Advanced.
Required
String (50)
payPalPreapprovedUpdateService_run
Set this field to true to request
payPalPreapprovedUpdate
Service.
Required
String (5)
payPalPreapprovedUpdateService_mpID
Billing agreement identifier (the mp_
id) that you received from PayPal.
Required
String (19)
paypal_mp_desc
Description of the goods or services
associated with the billing agreement.
Optional
String (no
length
limit)
paypal_mp_status
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.
Optional
String (8)
64
Chapter 3
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
String (6)

ACCEPT

ERROR

REJECT
invalidField_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.
String
(100)
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)
missingField_0...N
Required fields that were missing from the request. These
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)
payPalPreapproved
UpdateReply_desc
String (no
length limit)
payPalPreapproved
UpdateReply_mpMax
String (15)
payPalPreapproved
UpdateReply_mpStatus
Current status of the billing agreement. This field will contain
String (9)

Active

Canceled
payPalPreapproved
UpdateReply_payer
address).
String (no
length limit)
payPalPreapproved
UpdateReply_payerBusiness
String (no
length limit)
payPalPreapproved
UpdateReply_payerCountry
String (no
length limit)
payPalPreapproved
UpdateReply_payerID
String (no
length limit)
65
Chapter 3
Table 9
Billing Agreement Update Reply Fields (Continued)
Reply Field
Description
Data
Type &
Length
payPalPreapproved
UpdateReply_payerName
Customer's name.
String (no
length limit)
payPalPreapproved
UpdateReply_payerStatus
Status of the customer's email address. This field will
String (10)


unverified: Customer’s PayPal account is Unverified
payPalPreapproved
UpdateReply_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.
Integer (5)
payPalPreapproved
UpdateReply_reconciliationID
String (60)
payPalPreapproved
UpdateReply_requestDateTime
Time of the billing agreement update request. The format is
YYYY-MM-DDThh:mm:ssZ. For example, 2003-0811T22: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 (20)
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
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)
66
Chapter 3
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.
You must perform the credit within 60 days of the payment request.
Important
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
Data
Type &
Length
item_#_productCode
"Product Codes," page 152 for a list of valid values.
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.
See
description
String (15)
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.
67
Chapter 3
Table 10
PayPal Credit Request Fields (Continued)
Request Field
Description
Required /
Optional
Data
Type &
Length
merchantID
merchantID for evaluation, testing, and production.
Required
String (30)
Merchant-generated order reference or tracking
number. See the information about order tracking in
Required
String (50)
orderRequestToken
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
(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)
Currency used for the order. PayPal currently accepts
orders that use USD, CAD, EUR, GBP, or JPY only.
Required
String (5)
purchaseTotals_
grandTotalAmount
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.
See
description
String (15)
You must include either this field or item_#_unitPrice
in your request. See the information about items and
68
Chapter 3
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
String (6)

ACCEPT

ERROR

REJECT
invalidField_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
String
(100)
request. If you included multi-byte characters in this field in the
request, the returned value might contain corrupted characters.
String (50)
missingField_0...N
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
String
(100)
payPalCreditReply_amount
Amount of the credit.
String (15)
payPalCreditReply_
reasonCode
A numeric value corresponding to the result of the PayPal credit
request. See "Reason Codes," page 70 for a list of possible values.
Integer (5)
payPalCreditReply_
reconciliationID
transactions.
String (60)
payPalCreditReply_
requestDateTime
Time of the PayPal credit. The format is YYYY-MMDDThh:mm:ssZ. For example, 2003-08-11T22:47:57Z is
String (20)
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
String (26)
requestToken
field is an encoded string that contains no confidential information
such as an account or card verification number. The string can
String
(256)
69
Chapter 3
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.
Because CyberSource may add reply fields and reason codes at any time,
proceed as follows:
Important
Table 12

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.
Reason Codes
Reason
Code
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.
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.
70
Chapter 3
Table 12
Reason Codes (Continued)
Reason
Code
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.
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 (https://www.sandbox.paypal.com). 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.
71
CHAPTER
Requesting Services with
the SCMP API
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
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,
72
Chapter 4
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.
73
Chapter 4
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 www.paypal.com 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.
74
Chapter 4
Table 13
Methods for Specifying Shipping and Handling Charges
Method
Description
CyberSource:
Using a total freight
amount
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.
CyberSource:
Using an offer for the
freight amount
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.
PayPal:
freight amount
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.
PayPal:
Overriding the profilebased freight amount
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.
75
Chapter 4
Table 14
Methods for Specifying an Order’s Tax
Method
Description
CyberSource:
Using a total tax amount
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.
CyberSource:
Using an item-level tax
amount
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.
PayPal:
tax amount
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.
PayPal:
Overriding the profilebased tax amount
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>

Click PayPal Checkout to proceed with your PayPal payment.
This will take you to the PayPal login page.

%s
</body>
</html>
76
Chapter 4
The encrypted version of the button looks similar to this:
<form action="https://www.paypal.com/cgi-bin/webscr"
method="post"><input type="image" src="https://https://
www.paypal.com/en_US/i/btn/x-click-but23.gif" border="0"
name="submit"><input type="hidden" name="cmd" value="_s-xclick"><input
type="hidden" name="encrypted" value="-----BEGIN PKCS7----MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhM
CVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3NlMRUwEwYDSIb3DQ
EBAQUABIGAg0SFsADkAz5l03qK8we8z3zt86F9IZB8q8J+oCSjmBWgrZdh+VKHgPL2SKuRG
rifwXDCGFOJonjYK5EKExeSCmR/eZRUwzIpUmnKAY/r7Hqzd/e1IslJuFZ9/iKQO2hK/
wRq5VYIL22MGn0fY8GZ6CBmM76ceYojOe/XmlpUOLjANQnx2MVMI85hhpMAcaM-----END
PKCS7-----"</form>
The encrypted information in the above example has been shortened for
illustration. The actual length of the information is about 2000-3000 characters.
Note
The unencrypted version of the button looks similar to this:
<form action="https://www.paypal.com/cgi-bin/webscr"
method="post"><input type="image" src="https://https://
www.paypal.com/en_US/i/btn/x-click-but23.gif" 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="http://cancel.example.com"><input
type="hidden" name="undefined_quantity" value="1"><input type="hidden"
name="quantity" value="5"><input type="hidden" name="return"
value="http://success.example.com"><input 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="http://example.com/ipn"><input type="hidden" name="invoice"
value="0000028962"><input type="hidden" name="custom"
value="0000028962,1141312425560167905065,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
77
Chapter 4
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
Both
Required
String (50)
bill_country
Country of the billing address. Use the twocharacter ISO codes. See the Support Center
for a list of codes.
Both
Required
String (2)
bill_state
State or province of the billing address. Use
the two-character codes. See the Support
Center for a list of valid codes.
Both
Required if
country is
U.S. or
Canada
String (2)
bill_zip
Postal code for the billing address. The postal
code must consist of 5 to 9 digits.
Both
Required if
country is
U.S. or
Canada
String (10)
If the billing country is the U.S., the 9-digit
Example: 12345-6789
If the billing country is Canada, the 6-digit
Example: A1B 2C3
(3) Required if ship_to_country is US or CA.
78
Chapter 4
Table 15
Button Create Request-Level Fields (Continued)
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
button_type
Type of button to create. Use one of the
following values:
All
Required
String (30)
Regular
payment
Required
String (5)

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
currency
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_email
domain name. The field must be submitted in
the form [email protected] (for
example, [email protected]).
Both
Optional
String
(255)
customer_firstname
Both
Required
String (60)
customer_lastname
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.
Regular
payment
Optional
Decimal
(15)
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.
79
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
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)
Regular
payment
Optional
String (26)
link_to_request
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.
merchant_id
Your CyberSource merchant ID. Use the
same merchant_id for evaluation, testing,
and production.
Both
Required
String (30)
merchant_ref_number
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
Both
Required
String (50)
offer0...N
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.
Regular
payment
See
description
String (50)
80
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
paypal_amount
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.
Neither
See
description
N/A
paypal_cancel_return
URL of the Web page to show the customer if
the customer cancels the regular PayPal
payment, for example: http://
cancel.example.com.
Regular
payment
Optional
String
(255)
paypal_customer_
email
domain name. The field must be submitted in
the form [email protected] (for
example, [email protected]).
Both
Optional
String
(255)
paypal_handling
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.
Regular
payment
Optional
Decimal
(15)
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.
81
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
paypal_item_name
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.
Regular
payment
Optional
String
(127)
Regular
payment
Optional
String
(127)
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.
paypal_item_number
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.
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.
paypal_lc
Locale (language) for the billing agreement
pages. Use the two-character ISO country
codes.
Billing
agreement
Optional
String (2)
paypal_mp_cycle_
start
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.
Billing
agreement
Optional
Integer (2)
82
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
paypal_mp_desc
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 email confirmation from
PayPal when a billing agreement is created
or updated, in the transaction detail history for
each preapproved payment, and in the email
confirmation from PayPal when a
preapproved payment is processed.
Billing
agreement
Optional
String (no
length
limit)
paypal_mp_error
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:
Billing
agreement
Optional
Integer (1)

0 (default): No, do not show the error

1: Yes, show the error
paypal_mp_max
Maximum amount that you can withdraw from
the customer's account for a preapproved
payment.
Billing
agreement
Required
Decimal
(15)
paypal_mp_max_edit
Whether the customer can edit the monthly
maximum billing amount (paypal_mp_max).
Billing
agreement
Optional
Decimal
(1)
Billing
agreement
Optional
Decimal
(15)
paypal_mp_max_min

0 (default): No, the customer cannot edit
the value

1: Yes, the customer can edit the value
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.
83
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
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
Decimal
(15)
paypal_quantity
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.
Regular
payment
See
description
Nonnegative
integer
(no limit)
Both
Optional
String
(255)
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.
paypal_return
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: http://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
have configured to use with PayPal’s Auto
Return. See "Enabling Auto Return,"
page 32.
84
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
paypal_rm
Method of the FORM submission by which
PayPal returns data to your Web site. Use
Billing
agreement
Optional
Nonnegative
integer (1)
Regular
payment
Optional
Decimal
(15)
Regular
payment
Optional
Decimal
(15)
paypal_shipping

0 (default): POST

1: GET
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.
paypal_shipping2
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
85
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
paypal_tax
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.
Regular
payment
Optional
Decimal
(15)
If you are not using total_tax_amount or an
offer-level tax_amount field, paypal_tax
button.
This is a flat tax charge for the order. The
value is NOT multiplied by the number of
value overrides any profile-based tax charge
you have set. See "Specifying Tax for a
Regular Payment Button," page 75 for more
details.
paypal_undefined_
quantity
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.
Regular
payment
Optional
Nonnegative
integer (1)
ship_to_address1
First line of the address to which to ship the
product.
Regular
payment
Optional (1, 2)
String (60)
ship_to_address2
Second line of the address to which to ship
the product.
Regular
payment
Optional (2)
String (60)
ship_to_city
City to which to ship the product.
Regular
payment
Optional (1, 2)
String (50)
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
Optional (2)
String (2)
ship_to_firstname
First name of person receiving the product.
Regular
payment
Optional (2)
String (60)
ship_to_lastname
Last name of person receiving the product.
Regular
payment
Optional (2)
String (60)
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
Optional (2, 3)
String (2)
86
Chapter 4
Table 15
Request-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
ship_to_zip
Postal code for the shipping address. The
postal code must consist of 5 to 9 digits.
Regular
payment
Optional (2, 3)
String (10)
If the shipping country is the U.S., the 9-digit
Example: 12345-6789
If the shipping country is Canada, the 6-digit
Example: A1B 2C3
shipping_method
Shipping method for the product. For
example, FEDEX.
Regular
payment
Optional
String (10)
timeout
Number of seconds the system waits before
the transaction times out. The default is 110
seconds.
Both
Optional
Positive
integer (3)
total_tax_amount
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.
Regular
payment
Optional
Decimal
(15)
This value overrides any profile-based tax
charge you have set. See "Specifying Tax for
a Regular Payment Button," page 75 for more
details.
87
Chapter 4
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
Required/
Optional
Data
Type &
Length
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.
Regular
payment
See
description
Decimal
(15)
Regular
payment
See
description
String
(30)
Regular
payment
Optional
String
(30)
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.
merchant_
product_sku
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.
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.
product_code
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.
88
Chapter 4
Table 16
Button Create Offer-Level Fields (Continued)
Offer-Level Field
Description
Type of
Button
Required/
Optional
Data
Type &
Length
product_name
Product’s name. This information is not
displayed in the button but is displayed on the
transaction details screen in the Business
Center.
Regular
payment
See
description
String
(30)
Regular
payment
See
description
Nonnegative
integer
(10)
Regular
payment
Optional
Decimal
(15)
Required if product_code is NOT default,
stored_value, or one of the values related
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
Quantity of the product being purchased. The
default value is 1.
Required if product_code for the offer is NOT
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.
tax_amount
The sum of these values for all of the items
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
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.
89
Chapter 4
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
Information about the client library used to request the
transaction.
String (50)
ics_rcode
One-digit code that indicates whether the entire request was
successful. The field will contain one of the following values:
Integer (1)

-1: An error occurred

0: The request was declined

1: The request was successful
ics_rflag
One-word description of the result of the entire request. See
Table 18, page 91 for a list of possible values.
String (50)
ics_rmsg
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 (255)
merchant_ref_number
String (50)
paypal_button_
create_button_type
Type of button created. This field will contain one of the
following values:
String (30)

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.
paypal_button_create_
encrypted_form_data
Encrypted version of the button.
String (no
length limit)
paypal_button_
create_rcode
One-digit code that indicates whether the ics_paypal_button_
create request was successful. The field will contain one of the
following values:
Integer (1)



paypal_button_
create_rflag
One-word description of the result of the ics_paypal_button_
create request. See Table 18, page 91 for a list of possible
values.
String (50)
paypal_button_
create_rmsg
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 (255)
90
Chapter 4
Table 17
Button Create Reply Fields (Continued)
Reply Field
Description
Data Type &
Length
paypal_button_
create_time
Time of the button creation request. The format is YYYY-MMDDThhmmssZ. For example, 2003-08-11T224757Z is
Date and time
(20)
paypal_button_
create_trans_ref_no
Reference number for the transaction that you use to reconcile
your transactions.
String (60)
paypal_button_create_
unencrypted_form_data
Unencrypted version of the button.
String (no
length limit)
request_id
Unique identifier for the request generated by the client.
String (26)
request_token
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)
For more information, see the information about request tokens
in Getting Started with CyberSource Advanced.
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
Description
DINVALIDDATA
Data provided is not consistent with the request. For example, you
requested a product with negative cost.
DMISSINGFIELD
The request is missing a required field.
ESYSTEM
System error. See the documentation for your CyberSource client (for
important information about how to handle system errors and retries.
ETIMEOUT
The request timed out.
SOK
The transaction was successful.
91
Chapter 4
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.
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
Required
String (50)
bill_country
Country of the billing address. Use the two-character ISO
codes. See the Support Center for a list of codes.
Required
String (2)
bill_state
State or province of the billing address. Use the
two-character codes. See the Support Center for a list of
valid codes.
Required if
country is
U.S. or
Canada
String (2)
bill_zip
Postal code for the billing address. The postal code must
consist of 5 to 9 digits.
Required if
country is
U.S. or
Canada
String (10)
Required
String (5)
If the billing country is the U.S., the 9-digit postal code
Example: 12345-6789
If the billing country is Canada, the 6-digit postal code
Example: A1B 2C3
currency
92
Chapter 4
Table 19
Preapproved Payment Request-Level Fields (Continued)
Request-Level Field
Description
Required/
Optional
Data Type
& Length
customer_email
name. The field must be submitted in the form
[email protected] (for example,
[email protected]).
Optional
String (255)
customer_firstname
Required
String (60)
customer_lastname
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
See
description
Decimal (15)
ics_applications
Required
String (255)
Optional
String (26)
link_to_request
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
merchant_id
merchant_id for evaluation, testing, and production.
Required
String (30)
merchant_ref_number
Merchant-generated order reference or tracking number.
See the information about order tracking in Getting
Required
String (50)
offer0...N
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.
See
description
String (50)
paypal_customer_
email
name. The field must be submitted in the form
[email protected] (for example,
[email protected]).
Optional
String (255)
paypal_email_subject
Subject line of the confirmation email that will be sent to
the customer.
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
String (no
length limit)
paypal_mp_id
Billing agreement identifier (the mp_id).
Required
String (19)
93
Chapter 4
Table 19
Preapproved Payment Request-Level Fields (Continued)
Request-Level Field
Description
Required/
Optional
Data Type
& Length
paypal_payment_type
The type of PayPal payment funding source to use. Use
Optional
String (11)
Optional
Positive
integer (3)

Any (default): Any payment type is acceptable

EcheckOnly: eCheck

InstantOnly: Instant only
Make sure to provide the value exactly as shown above.
timeout
Number of seconds the system waits before the
transaction times out. The default is 110 seconds.
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
Data Type
& Length
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.
See
description
Decimal (15)
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.
merchant_product_sku
Product’s identifier code
Optional
String (30)
product_code
Optional
String (30)
product_name
Product’s name.
Optional
String (30)
94
Chapter 4
Table 20
Preapproved Payment Offer-Level Fields (Continued)
Offer-Level Field
Description
Required/
Optional
Data Type
& Length
quantity
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
See
description
Nonnegative
integer (10)
tax_amount
negative.
Optional
Decimal (15)
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
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.
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
transaction.
String (50)
ics_rcode
Integer (1)



ics_rflag
String (50)
ics_rmsg
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 (255)
merchant_ref_number
request. If you included multi-byte characters in this field, the
String (50)
95
Chapter 4
Table 21
Reply Field
Description
Data Type
& Length
paypal_preapproved_
payment_desc
String (no
length limit)
paypal_preapproved_
payment_exchange_rate
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 (15)
paypal_preapproved_
payment_fee_amount
PayPal fee amount charged for the transaction.
String (15)
paypal_preapproved_
payment_mp_max
String (15)
paypal_preapproved_
payment_mp_status
String (9)

Active

Canceled
paypal_preapproved_
payment_payer
address).
String (no
length limit)
paypal_preapproved_
payment_payer_business
String (no
length limit)
paypal_preapproved_
payment_payer_country
String (no
length limit)
paypal_preapproved_
payment_payer_id
String (no
length limit)
paypal_preapproved_
payment_payer_name
Customer's name.
String (no
length limit)
paypal_preapproved_
payment_payer_status
Status of the customer's email address. This field will contain
String (10)


paypal_preapproved_
payment_payment_date
PayPal's timestamp for the payment. Example: 18:30:30
Jan 1, 2000 PST.
String (20)
paypal_preapproved_
payment_payment_gross_
amount
The final amount charged including any shipping or taxes
from your PayPal profile.
String (15)
96
Chapter 4
Table 21
Reply Field
Description
Data Type
& Length
paypal_preapproved_
payment_payment_status
Status of the preapproved payment. This field will contain
String (9)

Completed

Pending (see reasons in paypal_preapproved_
payment_pending_reason below)
paypal_preapproved_
payment_payment_type
paypal_preapproved_
payment_pending_reason

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

String (7)
String (14)
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.


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 email
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.
97
Chapter 4
Table 21
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:
Integer (1)



paypal_preapproved_
payment_rflag
One-word description of the result of the ics_paypal_
preapproved_payment request. See Table 22, page 99 for
a list of possible values.
String (50)
paypal_preapproved_
payment_rmsg
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.
String (255)
paypal_preapproved_
payment_settle_amount
Amount deposited in your PayPal account after a currency
conversion.
String (15)
paypal_preapproved_
payment_tax_amount
Tax charged on the transaction.
String (15)
paypal_preapproved_
payment_time
Time of the preapproved payment request. The format is
YYYY-MM-DDThhmmssZ. For example, 2003-0811T224757Z is equal to August 11, 2003, at 10:47:57 P.M.
The T separates the date and the time. The Z indicates
UTC.
Date and
time (20)
paypal_preapproved_
payment_trans_ref_no
String (60)
paypal_preapproved_
payment_transaction_id
PayPal's unique transaction ID for the payment.
String (no
length limit)
paypal_preapproved_
payment_transaction_type
mercht-pmt.
Type of PayPal payment. This field will contain the value
request_id
Unique identifier for the request generated by the client.
String (26)
request_token
information such as an account or card verification number.
The string can contain a maximum of 256 characters.
String (256)
For more information, see the information about request
tokens in Getting Started with CyberSource Advanced.
98
Chapter 4
Reply Flags
The following table describes the rflags for ics_paypal_preapproved_payment.
Table 22
Preapproved Payment Reply Flags
Reply Flag
Description
DINVALIDDATA
DMISSINGFIELD
ESYSTEM
System error. See the documentation for your CyberSource client (SDK)
for important information about how to handle system errors and retries.
ETIMEOUT
SOK
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.
99
Chapter 4
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
Required
String (255)
merchant_id
Your CyberSource merchant ID. Use the same merchant_
id for evaluation, testing, and production.
Required
String (30)
merchant_ref_number
Order reference or tracking number that you provided in
the request. See the information about order tracking in
Required
String (50)
paypal_mp_desc
Description of the goods or services associated with the
billing agreement.
Optional
String (no
length limit)
paypal_mp_id
Billing agreement identifier (the mp_id) that you received
from PayPal.
Required
String (19)
paypal_mp_status
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.
Optional
String (8)
timeout
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
transaction.
String (50)
ics_rcode
Integer (1)



ics_rflag
String (50)
ics_rmsg
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 (255)
100
Chapter 4
Table 24
Request Field
Description
Data Type
& Length
merchant_ref_number
String (50)
paypal_preapproved_
update_desc
String (no
length limit)
paypal_preapproved_
update_mp_max
Decimal
(15)
paypal_preapproved_
update_mp_status
String (9)

Active

Canceled
paypal_preapproved_
update_payer
address).
String (no
length limit)
paypal_preapproved_
update_payer_business
String (no
length limit)
paypal_preapproved_
update_payer_country
String (no
length limit)
paypal_preapproved_
update_payer_id
String (no
length limit)
paypal_preapproved_
update_payer_name
Customer's name.
String (no
length limit)
paypal_preapproved_
update_payer_status
Status of the customer's email address. This field will contain
String (10)
paypal_preapproved_
update_rcode


One-digit code that indicates whether the ics_paypal_
preapproved_update request was successful. The field will



Integer (1)
paypal_preapproved_
update_rflag
One-word description of the result of the ics_paypal_
preapproved_update request. See Table 25, page 102 for a
list of possible values.
String (50)
paypal_preapproved_
update_rmsg
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 (255)
101
Chapter 4
Table 24
Request Field
Description
Data Type
& Length
paypal_preapproved_
update_time
Time of the billing agreement update request. The format is
YYYY-MM-DDThhmmssZ. For example, 2003-0811T224757Z is equal to August 11, 2003, at 10:47:57 P.M.
The T separates the date and the time. The Z indicates UTC.
Date and
time (20)
paypal_preapproved_
update_trans_ref_no
Reference number for the transaction that you use to reconcile
your transactions.
String (60)
request_id
String (26)
request_token
information such as an account or card verification number. The
string can contain a maximum of 256 characters.
String (256)
For more information, see the information about request tokens
in Getting Started with CyberSource Advanced.
Reply Flags
The following table describes the rflags for ics_paypal_preapproved_update.
Table 25
Billing Agreement Update Reply Flags
Reply Flag
Description
DINVALIDDATA
DMISSINGFIELD
ESYSTEM
System error. See the documentation for your CyberSource client for
important information about how to handle system errors and retries.
ETIMEOUT
SOK
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.
You must perform the credit within 60 days of the payment request.
Important
At this time, you can perform only one credit for an order, for either a partial
amount or the full amount of the payment.
102
Chapter 4
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.
The following table lists the request-level fields for ics_paypal_credit.
Table 26
Credit Request-Level Fields
Request-Level Field
Description
Required /
Optional
Data
Type &
Length
currency
Required
String (5)
grand_total_amount
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.
See
description
Decimal
(15)
You must include either this field or offer0 and the offerlevel field amount. See the information about offers and
ics_applications
Required
String
(255)
merchant_id
Your CyberSource merchant ID. Use the same merchant_
id for evaluation, testing, and production.
Required
String (30)
merchant_ref_number
Merchant-generated order reference or tracking number.
See the information about order tracking in Getting Started
with CyberSource Advanced.
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
Required
String
(256)
103
Chapter 4
Table 26
Credit Request-Level Fields (Continued)
Request-Level Field
Description
Required /
Optional
Data
Type &
Length
paypal_payment_
request_id
Request ID from the PayPal payment reply.
Required
String (26)
paypal_payment_
request_token
The request_token value returned from a previous
request for ics_paypal_preapproved_payment or ics_
paypal_preapproved_update.
Optional
String
(256)
Optional
Positive
integer (3)
information, such as an account number or card
verification number. The string can contain a maximum of
256 characters.
timeout
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
Data Type
& Length
amount
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.
See
description
Decimal
(15)
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.
merchant_
product_sku
Product’s identifier code
Optional
String (30)
product_code
Optional
String (30)
product_name
Product’s name.
Optional
String (30)
104
Chapter 4
Table 27
Credit Offer-Level Fields (Continued)
Offer-Level Field
Description
Required /
Optional
Data Type
& Length
quantity
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
See
description
Nonnegative
integer (10)
tax_amount
negative.
Optional
Decimal
(15)
The tax_amount field is additive. For example, if you send
the following offer lines:
amount:0.80
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.
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:
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
String (50)
105
Chapter 4
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:
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
Time of the PayPal credit request. The format is YYYY-MMDDThhmmssZ. For example, 2002-08-11T224757Z is equal to
August 11, 2002, at 10:47:57 P.M. The T separates the date and the
time. The Z indicates UTC.
Date and
Time (20)
paypal_credit_
trans_ref_no
CyberSource reports with your processor reports.
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.
String (256)
For more information, see the information about request tokens in
Reply Flags
The following table describes the rflags for ics_paypal_credit.
Table 29
Credit Reply Flags
Reply Flag
Description
DPAYMENTREFUSED
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.
DINVALIDDATA
Data provided is not consistent with the request. For example, you requested a product
with negative cost.
DMISSINGFIELD
ESYSTEM
System error. See the documentation for your CyberSource client for important
information about how to handle system errors and retries.
106
Chapter 4
Table 29
Credit Reply Flags (Continued)
Reply Flag
Description
ETIMEOUT
SOK
Testing
You can use CyberSource’s regular testing environment for sending test transactions.
Make sure your requests specify server_host=ics2test.ic3.com and server_
port=80.
The buttons generated by CyberSource’s test system submit the form to PayPal’s
Sandbox test environment (https://www.sandbox.paypal.com). 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.
107
CHAPTER
5
Creating a Shopping Cart
Button
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
In your request to create the button, set the button type to shopping_cart instead of
buy.
Step 2
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
Step 3
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.
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.
108
Chapter 5
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.
109
APPENDIX
Examples for the Simple
Order API
Note
A
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 2000-3000
characters.
110
Appendix A
Examples for the Simple Order API
Name-Value Pair Examples
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_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=http://paypalcancel.example.com
paypal_return=http://paypalsuccess.example.com
paypal_item_name=Nouveau Lamp
paypal_item_number=3362710
111
Appendix A
Example
Reply
requestID=0305782650000167905080
merchantReferenceCode=482046C3A7E9XYZ
decision=ACCEPT
reasonCode=100
payPalButtonCreateReply_reasonCode=100
payPalButtonCreateReply_buttonType=buy
payPalButtonCreateReply_amount=33.49
payPalButtonCreateReply_requestDateTime=2005-04-27T18:49:55Z
payPalButtonCreateReply_reconconciliationID=RYXWMQX04MC9
payPalButtonCreateReply_unencryptedFormData=
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="image" src="https://https://www.paypal.com/en_US/i/btn/x-clickbut23.gif" 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="3362710">
<input type="hidden" name="cancel_return" value="http://paypalcancel.example.com">
<input type="hidden" name="undefined_quantity" value="0">
<input type="hidden" name="quantity" value="0">
<input type="hidden" name="return" value="http://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="http://example.com/ipn">
<input type="hidden" name="invoice" value="RYXWMQX04MC9">
<input type="hidden" name="custom"
value="RYXWMQX04MC9,0305782650000167905080,482046C3A7E9XYZ"></
form>payPalButtonCreateReply_encryptedFormData=
<input type="hidden" name="encrypted" value=
"-----BEGIN PKCS7----MIIGTQYJKoZIhvcNAQcDoIIGPjCCBjoCAQAxggE6MIIBNgIBADCBnjCBmDELMAkGA1UEBhMCVVMxEzARBgNVB
XmlpUOLjANQnx2MVMI85hhpMAcaM
-----END PKCS7-----"></form>
112
Appendix A
Example
Request
payPalButtonCreateService_buttonType=preapproved_billing_agreement
merchantID=infodev
merchantReferenceCode=482046C3A7E94F5
billTo_state=CA
billTo_country=US
paypal_return=http://basuccess.example.com
paypal_mp_cycle_start=1
paypal_mp_desc=Gold Package Web Access at www.example.com
paypal_mp_max=20.00
paypal_mp_test_amount=10.00
113
Appendix A
Example
Reply
requestID=0305782650000167905081
decision=ACCEPT
reasonCode=100
payPalButtonCreateReply_reasonCode=100
payPalButtonCreateReply_buttonType=preapproved_billing_agreement
payPalButtonCreateReply_requestDateTime=2005-04-29T18:49:55Z
payPalButtonCreateReply_reconconciliationID=RYXWMQX04MC1
payPalButtonCreateReply_unencryptedFormData=
<input type="submit" name="submit" value="Approve Agreement">
<input type="hidden" name="cmd" value="_xclick-merchant">
<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="http://basuccess.example.com">
<input type="hidden" name="mp_desc" value="Gold Package Web Access at
www.example.com">
<input type="hidden" name="mp_custom"
value="RYXWMQX04MC1,0305782650000167905081,482046C3A7E94F3"></form>
payPalButtonCreateReply_encryptedFormData=
-----END PKCS7-----"></form>
114
Appendix A
Example
Request
payPalPreapprovedPaymentService_run=true
payPalPreapprovedPaymentService_mpID=B-123456789ABCDEFGH
merchantID=infodev
billTo_state=CA
billTo_country=US
paypal_email_subject=Your Monthly Payment for Gold Package at
www.example.com
Example
Reply
requestID=0305782650000167905052
decision=ACCEPT
reasonCode=100
payPalPreapprovedPaymentReply_reasonCode=100
payPalPreapprovedPaymentReply_requestDateTime=2005-05-27T18: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=56K11500RY2882507
paypayPalPreapprovedPaymentReply_desc=Gold Package Web Access at
www.example.com
payPalPreapprovedPaymentReply_mpMax=20.00
payPalPreapprovedPaymentReply_paymentType=instant
payPalPreapprovedPaymentReply_paymentDate=10:50:30 May 27, 2005 PST
payPalPreapprovedPaymentReply_paymentGrossAmount=19.95
payPalPreapprovedPaymentReply_taxAmount=0.00
115
Appendix A
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-123456789ABCDEFGH
merchantID=infodev
paypal_mp_status=Canceled
Example
Reply
requestID=0305782650000168405099
decision=ACCEPT
reasonCode=100
payPalPreapprovedUpdateReply_reasonCode=100
payPalPreapprovedUpdateReply_requestDateTime=2005-06-17T18:49:55Z
payPalPreapprovedUpdateReply_reconconciliationID=RYXWMQX04WC4
paypayPalPreapprovedUpdateReply_desc=Gold Package Web Access at
www.example.com
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
payPalCreditService_payPalPaymentRequestID=0305782650000167905052
116
Appendix A
Example
Reply
requestID=0305782650000167943227
decision=ACCEPT
reasonCode=100
payPalCreditReply_reasonCode=100
payPalCreditReply_requestDateTime=2005-06-19T18:49:55Z
payPalCreditReply_reconconciliationID=RYX9483QX04WC4
payPalCreditReply_amount=10.00
Example
Request
payPalButtonCreateService_buttonType=shopping_cart
merchantID=infodev
paypal_item_name_1=Book
paypal_item_number_1=999999
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_quantity_2=1
paypal_tax_2=0.00
// Include the API fields for the billing
// and shipping information here
117
Appendix A
XML Examples
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>
<state>CA</state>
</shipTo>
<purchaseTotals>
<currency>USD</currency>
<taxAmount>2.55</taxAmount>
<grandTotalAmount>25.99</grandTotalAmount>
<freightAmount>4.95</freightAmount>
</purchaseTotals>
<paypal>
<cancel_return>http://paypalcancel.example.com</cancel_return>
<return>http://paypalsuccess.example.com</return>
<item_name>Nouveau Lamp</item_name>
<item_number>3362710</item_number>
</paypal>
<payPalButtonCreateService run="true">
<buttonType>buy</buttonType>
</payPalButtonCreateService>
</requestMessage>
118
Appendix A
Example
Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23">
<c:merchantReferenceCode>482046C3A7E94F5
</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:payPalButtonCreateReply>
<c:encryptedFormData>
-----END PKCS7-----"></form>
</c:encryptedFormData>
<c:unencryptedFormData>
119
Appendix A
<input type="hidden" name="cancel_return" value="http://paypalcancel.example.com">
<input type="hidden" name="return" value="http://paypalsuccess.example.com">
</c:unencryptedFormData>
<c:requestDateTime>=2005-04-27T18:49:55Z</c:requestDateTime>
<c:recondiliationID>RYXWMQX04MC9</c:reconciliationID>
<c:buttonType>buy</c:buttonType>
</c:payPalButtonCreateReply>
</c:replyMessage>
120
Appendix A
Example
Request
<billTo>
<state>CA</state>
</billTo>
<paypal>
<return>http://basuccess.example.com</return>
<mp_cycle_start>1</mp_cycle_start>
<mp_desc>Gold Package Web Access at www.example.com</mp_desc>
<mp_test_amount>10.00</mp_test_amount>
</paypal>
<buttonType>preapproved_billing_agreement</buttonType>
</requestMessage>
121
Appendix A
Example
Reply
<c:payPalButtonCreateReply>
<c:encryptedFormData>
-----END PKCS7-----"></form>
</c:encryptedFormData>
<c:unencryptedFormData>
www.example.com">
</c:unencryptedFormData>
<c:requestDateTime>2005-04-29T18:49:55Z</c:requestDateTime>
<c:buttonType>preapproved_billing_agreement</c:buttonType>
</c:payPalButtonCreateReply>
</c:replyMessage>
122
Appendix A
Example
Request
<billTo>
<state>CA</state>
</billTo>
<purchaseTotals>
</purchaseTotals>
<paypal>
<email_subject>Your Monthly Payment for Gold Package at
www.example.com</
email_subject>
</paypal
<payPalPreapprovedPaymentService run="true">
<mpID>B-123456789ABCDEFGH</mpID>
</payPalPreapprovedPaymentService>
</requestMessage>
123
Appendix A
Example
Reply
<c:purchaseTotals>
</c:purchaseTotals>
<c:payPalPreapprovedPaymentReply>
<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>56K11500RY2882507</c:transactionID>
<c:desc>Gold Package Web Access at www.example.com</c:desc>
<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>
124
Appendix A
Example
Request
<paypal>
<mp_status>Canceled</mp_status>
</paypal>
<payPalPreapprovedUpdateService run="true">
<mpID>B-123456789ABCDEFGH</mpID>
</payPalPreapprovedUpdateService>
</requestMessage>
Example
Reply
<payPalPreapprovedUpdateReply>
<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 www.example.com</c:desc>
<c:mpMax>20.00</c:mpMax>
</c:payPalPreapprovedPaymentReply>
</c:replyMessage>
125
Appendix A
Processing a Credit
Example
Request
<purchaseTotals>
</purchaseTotals>
<payPalCreditService run="true">
<payPalPaymentRequestID>0305782650000167905052</payPalPaymentRequestID>
</payPalCreditService>
</requestMessage>
Example
Reply
<purchaseTotals>
</c:purchaseTotals>
<c:payPalCreditReply>
<c:amount>10.00</c:amount>
<c:reconconciliationID>RYX9483QX04WC4</c:reconconciliationID>
</c:payPalCreditReply>
</c:replyMessage>
126
Appendix A
Example
Request
<billTo>

</billTo>
<shipTo>

</shipTo>
<purchaseTotals>
</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>
<buttonType>shopping_cart</buttonType>
</requestMessage>
127
APPENDIX
Examples for the SCMP API
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 2000-3000 characters.
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_item_name=Nouveau Lamp
paypal_item_number=3362710
server_host=ics2test.ic3.com
server_port=80
128
Appendix B
Example
Reply
request_id=0305782650000167905080
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.
129
Appendix B
paypal_button_create_button_type=buy
paypal_button_create_amount=33.49
currency=USD
paypal_button_create_time=2005-04-27T184955Z
paypal_button_create_trans_ref_no=RYXWMQX04MC9
paypal_button_create_unencrypted_form_data=
<input type="image" src="https://https://www.paypal.com/en_US/i/btn/xclick-but23.gif" border="0" name="submit">
<input type="hidden" name="cancel_return" value="http://
paypalcancel.example.com">
<input type="hidden" name="return" value="http://
paypalsuccess.example.com">
value="RYXWMQX04MC9,0305782650000167905080,482046C3A7E9XYZ"></form>
130
Appendix B
paypal_button_create_encrypted_form_data=
<input type="image" src="https://https://www.paypal.com/en_US/i/btn/xclick-but23.gif" border="0" name="submit">
"-----BEGIN PKCS7----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
131
Appendix B
Example
Request
merchant_id=infodev
merchant_ref_number=482046C3A7E94F5
button_type=preapproved_billing_agreement
bill_city=San Jose
bill_state=CA
bill_zip=95127
bill_country=US
paypal_return=http://basuccess.example.com
paypal_mp_cycle_start=1
paypal_mp_desc=Gold Package Web Access at www.example.com
paypal_mp_max=20.00
paypal_mp_test_amount=10.00
server_port=80
132
Appendix B
Example
Reply
request_id=0305782650000167905081
request_token=rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv
ics_rcode=1
ics_rflag=SOK
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=2005-04-29T184955Z
paypal_button_create_trans_ref_no=RYXWMQX04MC1
paypal_button_create_unencrypted_form_data=
www.example.com">
paypal_button_create_encrypted_form_data=
<input type="hidden" name="encrypted" value="
-----END PKCS7-----"></form>
133
Appendix B
Example
Request
ics_applications=ics_paypal_preapproved_payment
merchant_id=infodev
bill_city=San Jose
bill_state=CA
bill_zip=95127
bill_country=US
currency=USD
paypal_mp_id=B-123456789ABCDEFGH
paypal_email_subject=Your Monthly Payment for Gold Package at
www.example.com
server_port=80
Example
Reply
request_id=0305782650000167905052
ics_rcode=1
ics_rflag=SOK
paypal_preapproved_payment_rcode=1
paypal_preapproved_payment_rflag=SOK
134
Appendix B
paypal_preapproved_payment_rmsg=Request was processed successfully.
currency=USD
paypal_preapproved_payment_time=2005-05-27T184955Z
paypal_preapproved_payment_trans_ref_no=RYXWMQX04MC2
paypal_preapproved_payment_desc=Gold Package Web Access at
www.example.com
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=56K11500RY2882507
paypal_preapproved_payment_pending_reason=none
paypal_preapproved_payment_transaction_type=mercht-pmt
135
Appendix B
Example
Request
ics_applications=ics_paypal_preapproved_update
merchant_id=infodev
paypal_mp_ip=B-123456789ABCDEFGH
paypal_mp_status=Canceled
server_port=80
136
Appendix B
Example
Reply
request_id=0305782650000168405099
ics_rcode=1
ics_rflag=SOK
paypal_preapproved_update_rcode=1
paypal_preapproved_update_rflag=SOK
paypal_preapproved_update_rmsg=Request was processed successfully.
currency=USD
paypal_preapproved_update_time=2005-06-17T184955Z
paypal_preapproved_update_trans_ref_no=RYXWMQX04WC4
paypal_preapproved_update_desc=Gold Package Web Access at
www.example.com
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
137
Appendix B
Processing a Credit
Example
Request
ics_applications=ics_paypal_credit
merchant_id=infodev
paypal_payment_request_id=0305782650000168405099
order_request_token=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv
currency=USD
server_port=80
Example
Reply
request_id=0305782650000167943227
ics_rcode=1
ics_rflag=SOK
paypal_credit_rcode=1
paypal_credit_rflag=SOK
paypal_credit_rmsg=Request was processed successfully.
paypal_credit_time=2005-05-19T18:49:55Z
paypal_credit_trans_ref_no=RYX9483QX04WC4
paypal_credit_amount=10.00
currency=USD
138
Appendix B
Example
Request
button_type=shopping_cart
merchant_id=infodev
paypal_item_name_1=Book
paypal_quantity_1=1
paypal_tax_1=0.00
paypal_item_name_2=DVD
paypal_quantity_2=1
paypal_tax_2=0.00
// Include the API fields for the billing
// and shipping information here
139
APPENDIX
PayPal Reply Variables
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
PayPal’s PDT Reply Variables
Variable
Description
tx
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.
st
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
Total amount of the payment.
cc
Currency code.
cm
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.
sig
PayPal’s signature.
140
Appendix C
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
Description
first_name
Customer's personal first name if the customer does not have a PayPal Business or
Premier account.
last_name
Customer's personal last name if the customer does not have a PayPal Business or
Premier account.
mp_custom
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.
mp_cycle_start
Day of the month on which the monthly billing cycle starts.
mp_desc
Pass-through variable. Contains exactly what you provided in paypal_mp_desc
when you created the button.
mp_id
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-123456789ABCDEFGH.
mp_max
The maximum monthly amount that the customer agreed to for the preapproved
payments.
mp_pay_type
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
141
Appendix C
Table 31
PayPal’s HTML Reply Variables for Creating a Billing Agreement (Continued)
HTML Variable
Description
mp_status
The status of the billing agreement. The field will contain one of the following values:
mp_test_result

0: The customer accepted the billing agreement

1: The customer did not accept the billing agreement
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

passed

failed
The value passed is a reasonable assurance that the customer's account can be
billed in the future.
payer_business_
name
Name of the customer's business, returned only if the customer has a PayPal
payer_email
Customer's primary email address.
payer_id
Customer's unique PayPal-generated identification number.
payer_status
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
142
Appendix C
Table 31
PayPal’s HTML Reply Variables for Creating a Billing Agreement (Continued)
HTML Variable
Description
reason_code
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.
143
Appendix C
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 http:// 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=0000015593%2C1036035196510167905065&
payer_status=verified&
business=jdoe%40companyABC.com&
address_country=United+States&
num_cart_items=1&
mc_handling1=0.00&
address_city=bloomington&
payer_email=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_email=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
144
Appendix C
Table 32
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).
128
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
Merchant’s email address or account ID. Equivalent to receiver_
email if payment is sent to primary account, and essentially an echo
of the business variable that was passed to PayPal in the button
127
custom
CyberSource populates this field with various identifiers, and PayPal
echoes the field in the IPN message. The field contains six identifiers
separated by commas.
255
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
Exchange rate used if a currency conversion occurred.
first_name
64
invoice
CyberSource populates this field with an identifier, and PayPal
echoes the field in the IPN message.
255
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
and
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).
127
item_name#
145
Appendix C
Table 32
IPN Variables for Regular Payments (Continued)
Variable
Description
Max
Length
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.
127
last_name
64
mc_currency
Currency of the payment. The value will be USD, CAD, EUR, GBP, or
JPY.
mc_fee
Transaction fee for the payment. The mc_gross minus mc_fee will
equal the amount deposited into the receiver_email 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.
mc_gross
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.
and
item_number#
and
mc_gross_#
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.
mc_handling
Total handling amount associated with the transaction.
and
item (mc_handling1, and so on).
mc_handling#
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.
mc_shipping
Total shipping amount associated with the transaction.
and
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.
mc_shipping#
notify_version
Version of the IPN message. Example: 1.6
num_cart_items
For a shopping cart transaction, number of items in the cart.
option_name1
Option 1 name as requested by you.
and
item (option_name1_1, and so on).
option_name1_#
64
146
Appendix C
Table 32
Variable
Description
Max
Length
option_name2
Option 2 name as requested by you.
64
and
item (option_name2_1, and so on).
option_name2_#
option_selection1
Option 1 choice as entered by the customer.
and
item (option_selection1_1, and so on).
option_selection1_#
option_selection2
Option 2 choice as entered by the customer.
and
item (option_selection2_1, and so on).
option_selection2_#
200
200
parent_txn_id
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.
17
payer_business_name
Customer’s company name.
127
payer_email
Customer’s primary email address. Use this email to provide any
credits.
127
payer_id
PayPal’s unique customer ID.
13
payer_status
Whether the customer has a verified account. This field will contain

Verified: Customer has a Verified PayPal account

Unverified: Customer has an Unverified PayPal account
payment_date
PayPal’s time stamp. Example: 18:30:30 Jan 1, 2000 PST.
payment_fee
USD transaction fee for the payment. The payment_gross minus
payment_fee will equal the amount deposited into the
receiver_email 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.
payment_gross
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.
147
Appendix C
Table 32
Variable
Description
payment_status
Status of the payment. This field can contain one of the following
values:
payment_type

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.

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.
Max
Length
Indicates whether the payment is instant or delayed. This field will

echeck: Electronic check

instant: Credit card, PayPal balance, or Instant Transfer
148
Appendix C
Table 32
Variable
Description
pending_reason
Reason if payment_status=Pending. This field contains one of
these values:

Max
Length
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.


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 email 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.

quantity
and
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).
127
quantity#
reason_code
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.
149
Appendix C
Table 32
Variable
Description
Max
Length
receiver_email
Merchant’s primary email address. If the payment is sent to a nonprimary email address on your PayPal account, the receiver_
email will still be your primary email.
127
receiver_id
Merchant’s unique account ID (same as the referral ID).
13
settle_amount
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).
settle_currency
Currency of settle_amount.
tax
Amount of tax charged on the payment.
and
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.
tax#
txn_id
PayPal’s unique transaction ID.
txn_type
Type of transaction. This field will contain one of the following values:
verify_sign

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.
17
Encrypted string used to validate the authenticity of the transaction.
150
Appendix C
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_email

reason_code

mp_custom

payer_id
See "Reply Variables for Creating a Billing Agreement," page 141 for descriptions of these
variables.
151
APPENDIX
D
Product Codes
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
Definition
adult_content
Adult content.
coupon
Coupon applied to the entire order.
default
Default value for the product code. CyberSource uses
default when a request message does not include a
value for the product code.
electronic_good
Electronic product other than software.
electronic_software
Software distributed electronically rather than on disks or
other media.
gift_certificate
Gift certificate.
handling_only
Fee that you charge your customer to cover your
administrative selling costs.
service
Service that you perform for your customer.
shipping_and_handling
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.
shipping_only
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
Subscription to a web site or other content.
152
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
Buyer Complaint Process 21
C
cancel URL 9, 34
canceling billing agreements 12
SCMP API 99
Simple Order API 63
chargebacks 21
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
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
business 38
currencies, using multiple 33
business account 8
custom 38
button creation 9
billing agreement 11
SCMP API 72
shopping cart 108
Simple Order API 37
CyberSource reports 17
D
date and time format 55
SCMP API 91
Buy Now buttons. See regular payments
153
Index
E
M
electronic checks 24
email notifications 10, 24
MIP. See billing agreements or preapproved
payments
encrypted button 41
SCMP API 76
mp_id 11, 42, 141
SCMP API 77
examples 110
SCMP API 128
mp_test_result 151
F
N
fraud test 151
notify_url 38
multiple currencies 33
fulfilling orders 15
funding sources 8
O
funds transfer 33
order fulfillment 15
order tracking 14
G
GMT 55
P
Payment Batch Summary Report 18
H
Payment Data Transfer. See PDT
Hosted Order Page
Business Center settings 35
PayPal settings 24
Payment Events Report 12, 13, 17
I
payments. See regular payments or preapproved
payments
ics_paypal_button_create 72
PayPal Account, opening and configuring 23
ics_paypal_credit 102
PayPal business account 8
ics_paypal_preapproved_payment 92
paypal_business 38
ics_paypal_preapproved_update 99
payPalButtonCreateService 37
ics_rcode reply field 90
paypal_cancel_return 34
ics_rflag reply field 90
paypal_cmd 38
ics_rmsg reply field 90
payPalCreditService 67
ics_tax 72, 92
paypal_custom 38
invoice 38
paypal_invoice 38
IPN
paypal_notify_url 38
described 16
message forwarding 34
notification URL 26
variables 144
Payment Invoice Summary Report 18
Payment Submission Detail Report 18
payPalPreapprovedPaymentService 56
payPalPreapprovedUpdateService 63
paypal_return 10, 32, 34
154
Index
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
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
reconciliation IDs 14
shipping and handling 39
SCMP API 74
reconciliation with settlement file 33
shipping goods 15
refunds
described 13
SCMP API 102
Simple Order API 67
shopping cart button 108
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
success URL 9, 10, 32
signing up
CyberSource 34
PayPal 23
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
reports 17
request ID
and credits 103
155
Index
U
unencrypted button 41
SCMP API 76
updating billing agreements 12
SCMP API 99
Simple Order API 63
UTC 55
156

CyberSource PayPal Services Implementation Guide ®

Transcription

Similar documents

Membership Registration Form 2015

Exchange Merchandise Authorization Form

Connaught Skating Club – Mark Pillay Seminar

SuiteCommerce Site Builder

ASBOG EXAMINATION SCORE REQUEST

Love Letters Humane Society of Morgan County

Pottery Wheel Mania!

PayPal Merchant Cases

Got Game? - AnswerLab

Seehunde Seehundbank Wattenmeer Zeehond bank