PayPal_Express_SO

Title Page

PayPal Express Checkout Services

Using the Simple Order API

The PayPal Express Service is no longer supported by Cybersource.

This guide is for reference by existing customers only.

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 sales@cybersource.com 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:

http://www.cybersource.com/support

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

Authorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation.

Cybersource, Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, and

Cybersource Connect are trademarks and/or service marks of Cybersource Corporation. Visa, Visa International,

Cybersource, the Visa logo, and the Cybersource logo are the registered trademarks of Visa International in the

United States and other countries. All other trademarks, service marks, registered marks, or registered service

marks are the property of their respective owners.

Revision: February 2021

PayPal Express Checkout Services Using the Simple Order API | 3

CONTENTS

Contents

Recent Revisions to This Document 6

About This Guide 7

Audience 7

Purpose 7

Conventions 7

Related Documentation

 Getting Started with CyberSource Advanced for the Simple Order API (PDF | HTML)

describes how to get started using the Simple Order API.

 The Reporting Developer Guide (PDF | HTML) describes how to download reports:

Refer to the Support Center for complete Cybersource technical documentation:

http://www.cybersource.com/support_center/support_documentation

Customer Support

For support information about any Cybersource service, visit the Support Center:

http://www.cybersource.com/support

Table 1 Text Conventions

Convention Meaning

boldface Boldface type indicates API field names in text, API service names in text,

and graphical user interface elements that you must act upon.

italic Italic type indicates book titles and first use of special terms.

Screen text

Monospace type indicates code in examples or possible values for API

fields.

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 9

Introduction to PayPal

Express Checkout

When you use the PayPal Express Checkout services:

 Cybersource handles the interface with PayPal Express Checkout and ensures that

the interface is secure. No additional security key management is required on your

part.

 You manage your PayPal Express Checkout payments in the Cybersource Business

Center as you would other payment types. You can search for the payment, view its

details, and apply a credit just as you would with credit card payments.

 You use a single set of Cybersource reports to manage all your types of payments,

including your PayPal Express Checkout payments.

Because your customer completes the order on your web site rather than on the PayPal

web site, you can:

 Receive real-time notification of successful payments.

 Enable your customers to be directed to your web site’s final confirmation page.

 Receive notification from Cybersource that the customer's address has been confirmed

and that you are eligible for coverage under the PayPal Seller Protection Policy, if you

are enrolled in this PayPal plan. For more information about the features that

Cybersource supports, see the Seller Protection Policy information in "Disputes and

Chargebacks," page 20.

 Receive the PayPal order ID, authorization ID, and capture ID from Cybersource.

PayPal Express Checkout is not supported on an iFrame integration.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

PayPal requires you to provide two different ways for your customers to access PayPal

Express Checkout. These methods are described in the following table.

Terminology

The following table describes the terminology for PayPal Express Checkout.

Prerequisites

Before you process PayPal Express Checkout payments:

 Install a Cybersource client.

See the information about clients in Getting Started with CyberSource Advanced for

the Simple Order API.

 Contact Cybersource Customer Support to configure your Cybersource account.

Table 2 PayPal Express Checkout Methods

Method Description

Shortcut Place the Checkout with PayPal button on your checkout page.

Payment Place the PayPal button on your payment page or add PayPal as a choice in

your payment drop-down list.

Table 3 PayPal Express Checkout Terminology

Term Description

Authorization ID PayPal parameter that identifies an authorization. More than one

authorization ID can be associated with an order. Use for a follow-on

authorization reversal or capture.

Billing Agreement ID PayPal parameter that identifies a specific billing agreement between

you and your customer. Use to perform a reference transaction or to

cancel a billing agreement.

Capture ID PayPal parameter that identifies a capture. Use for a follow-on full or

partial refund.

Honor Period Amount of time after an authorization during which funds are held and

guaranteed available. If the honor period expires, the capture could be

declined.

Order ID Transaction identifier created by PayPal and returned to you through

Cybersource as a reply in the third API call. Used by Cybersource to

initiate an authorization or re-authorization.

Session Token Identifier that the Cybersource API passes to you. Use to merge the

API calls. Has a lifetime of three hours.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

 If you are using the Simple Order API with XML, make sure you are using the correct

API version for the features you are implementing. CyberSource recommends that

you use the most recent API version.

For general information about the API versions, see Getting Started with CyberSource

Advanced for the Simple Order API. The following table shows which Simple Order

API version to use for the PayPal Express Checkout features.

 Set up your PayPal account.

When you open your PayPal business account, PayPal assigns you a PayPal account

manager who helps you configure your PayPal account.

To set up your PayPal account:

Step 1 Log in to https://developer.paypal.com using your master Sandbox developer account.

To make testing easier, check the Log me in automatically box. This option makes it

quicker for you to approve the test payments you process through the Cybersource and

PayPal test environments.

Step 2 Click Accounts in the left pane to view your Sandbox Business and Buyer accounts.

Table 4 Choosing the Simple Order API Version

Feature Simple Order API

Version

Standard orders Version 1.29 or later

Custom orders Version 1.32 or later

Functionality introduced in May 2008:

 Requesting the customer’s billing address

 Using the invoice number, error code, and correlation ID fields

Version 1.36 or later

Billing agreements and reference transactions Version 1.47 or later

Item-level request fields

Note To enable item-level fields, contact CyberSource

Customer Support to have your account configured for this

feature.

Version 1.73 or later

Functionality introduced in October 2012:

 Item-level reply fields for the Get Details service

 Get Transaction Details service

 Logo image field

Note Contact CyberSource Customer Support to have your

account configured for these features.

Version 1.77 or later

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Step 3 Set up or select an account.

 To test PayPal Express Checkout transactions, you need to set up a personal test

account and a business test account.

 If you need to set up Business seller accounts from which to run test transactions, do

so here.

 If you already set up an account, select the Business or Premier account that you will

use as your seller account, which is the account you set up with Cybersource as your

PayPal merchant ID for receiving payments through Cybersource.

Step 4 Navigate to https://www.sandbox.paypal.com/signin/ in a new browser tab.

The PayPal web site displays a new window.

Step 5 In the new window, log in using your Sandbox seller account credentials.

Step 6 Choose the My Account tab and click Profile. The Profile Summary page is displayed.

Step 7 Click My selling tools in the left pane.

Step 8 In the Selling online section, click the Update link under API access.

Step 9 Click Add or Edit API Permissions link under Pre-built Payment Solution.

Step 10 Click Add New Third Party button on the Manage Third Party Access page.

Step 11 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 12 Click Lookup.

Step 13 Check the following permissions:

 Use Express Checkout to process payments.

 Issue a refund for a specific transaction.

 Authorize and capture your PayPal transactions.

 Obtain information about a single transaction.

 Search your transactions for items that match specific criteria and display the results.

 Charge an existing customer based on a prior transaction.

 Create and manage Recurring Payments.

 Obtain authorization for pre-approved payments and initiate pre-approved

transactions.

If you are going to use reference transactions, contact your PayPal representative to

enable billing agreements and reference transactions.

Step 14 Click Add.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Step 15 To edit or view permissions, click the Edit Third Party button on the Manage Third Party

Access page.

Step 16 You must provide the username of your Seller test account to Cybersource Customer

Support to enable your account for Express Checkout.

PayPal Express Checkout Flows

PayPal offers two Express Checkout customer experience flows.

 Traditional Express Checkout

 In-Context Express Checkout

Traditional Express Checkout Flow

When your customer is ready to pay for the products selected from your web site:

1 The customer clicks Checkout with PayPal on your checkout page or clicks PayPal on

your payment page.

2 Your web site redirects the customer’s browser to the PayPal web site.

3 The customer logs in and selects a payment method and shipping address.

4 PayPal redirects the customer’s browser to your web site so that the customer can

complete the purchase.

The redirection URL controls the customer experience. For more information, see

"Redirection URLs," page 25.

In-Context Express Checkout Flow

When your customer is ready to pay for the products selected from your web site:

1 The customer clicks Checkout with PayPal on your checkout page or clicks PayPal on

your payment page.

2 Your web site remains in view while a PayPal window appears.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

3 The customer logs in and selects a payment method and shipping address.

 In-context web flow:

 In-context mobile flow:

4 PayPal redirects the customer’s browser to your web site so that the customer can

complete the purchase.

For In-Context Express Checkout, follow the instructions:

 For basic integration, see:

https://developer.paypal.com/docs/classic/express-checkout/in-context/integration/

#basic-integration.

 For advanced settings, see:

https://developer.paypal.com/docs/classic/express-checkout/in-context/integration/

#advanced-settings.

The redirection URL controls the customer experience flow. For more information, see

"Redirection URLs," page 25.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

PayPal Express Checkout Orders

Standard Orders

A PayPal Express Checkout standard order enables you to obtain an authorization

(without needing to explicitly call for an authorization) and to perform captures, each for a

partial amount of the authorization. Use a standard order if your company meets one or

more of the following criteria:

 You do not usually run out of products sold.

 You do not usually have back orders.

 You do not accept advanced orders.

A PayPal Express Checkout standard order consists of three API calls, the last of which

contains an implicit authorization, and a fourth API call for an explicit capture. The

authorization confirms that the funds are available. The capture transfers the funds from

the customer’s account to your account.

Table 5 Types of PayPal Express Checkout Orders

Group Type of Order

Standard Orders Regular Order

Sale

Custom Orders Immediate Partial Sale

Delayed Authorization

Delayed Capture

Billing Agreements Billing Agreement with Payment

Billing Agreement without Payment

Reference Transaction

Cybersource recommends that you use custom orders instead of standard

orders because custom orders:

 Allow more flexibility with respect to partial shipments and back orders by

allowing multiple authorizations and captures for each order.

 Allow for more detailed control of Order Setup and Authorization

processing.

See "Custom Orders," page 15.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

To authorize a standard order, call these three services:

1 Set

2 Get Details

3 Do Payment

There are two ways to perform the capture:

 For a regular order, call the Do Capture service separately after calling the three

authorization services.

 For a sale, call the Do Capture service at the same time as the Do Payment service.

The following table lists the service calls for a standard order.

Custom Orders

A PayPal Express Checkout custom order enables you to perform multiple authorizations

and multiple captures for each of the separate authorizations. Use a custom order if your

company meets one or more of the following criteria:

 You usually have split shipments.

 You accept advanced orders for products that are not available now but will be

available in the next 364 days.

 You usually have back orders for which the customer needs to wait longer than a

week.

 You usually perform bank card reauthorizations.

A PayPal Express Checkout custom order consists of three parts:

1 Order setup records the fact that the customer has authorized you to debit their account

for a defined amount of money, which is up to 115% of the order amount.

2 Authorization confirms that the funds are available.

3 Capture transfers the funds from the customer’s account to your account.

Table 6 Service Calls for a Standard Order

For a Regular Order For a Sale

1Set

2 Get Details

3 Do Payment

4 Do Capture

1Set

2 Get Details

3 Do Payment & Do Capture

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

All three types of custom orders start with a call to the Set service followed by a call to the

Get Details service. The remaining calls are different for each type of custom order. You

can combine the different types of custom orders presented here when you create your

custom order:

 For an immediate partial sale, call the Order Setup, Authorization, and Do Capture

services in the same request.

 For a delayed authorization, call the Order Setup service. Then call the Authorization

service one or more times (up to the total amount of the order), and then call the Do

Capture service for each authorization.

 For a delayed capture, call the Order Setup service. Then call the Authorization

service, and then call the Do Capture service multiple times for the authorization. You

can make additional calls to the Authorization service, and then call the Do Capture

service multiple times for each authorization.

The following table lists the service calls for each type of custom order. The steps shown

for an immediate partial sale are listed exactly as they should be completed. The steps

shown for the delayed authorization and delayed capture are examples of the calls you

can make. Table 7, "Service Call Examples for Custom Orders," on page 17 provides

examples of a Delayed Authorization and a Delayed Capture.

Table 7 Service Calls for a Custom Order

For an Immediate

Partial Sale

For a Delayed Authorization For a Delayed

Capture

1Set

2 Get Details

3 Order Setup, Authorization,

& Do Capture

1Set

2Get Details

3 Order Setup

4 Authorization

5 Do Capture

6 Authorization

7 Do Capture

1Set

2 Get Details

3Order Setup

4 Authorization

5 Do Capture

6 Do Capture

7 Authorization

8 Do Capture

9 Do Capture

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Billing Agreements

A PayPal Express Checkout billing agreement enables you to use a billing agreement ID

for future billing without requiring your customer to specifically authorize each future

payment. After you create a billing agreement, when you send a request to bill the

customer for a specified amount, you use the billing agreement to process the PayPal

Express Checkout order.

If you are adding this functionality to an existing PayPal Express Checkout

implementation, contact your PayPal representative to enable billing agreements and

reference transactions.

Use one of the following scenarios to create a billing agreement:

 For a billing agreement with payment, perform a standard order as described in

"Standard Orders," page 14, but include the billing agreement fields in your service

requests. This scenario performs a PayPal Express Checkout payment and creates a

billing agreement at the same time.

 For a billing agreement without payment, call the Set, Get Details, and Create

Agreement services to create a billing agreement while performing a PayPal Express

Checkout payment for USD 0.00.

After you create a billing agreement, perform a PayPal Express Checkout payment by

using the Reference Transaction scenario: call the Do Reference Transaction,

Table 8 Service Call Examples for Custom Orders

For a Delayed

Authorization

For a Delayed Capture

1Set

2 Get Details

3 Order Setup for $1000

4 Authorization for $700

5 Do Capture for $700

6 Authorization for $300

7 Do Capture for $300

1Set

2Get Details

3 Order Setup for $1000

4 Authorization for $700

5 Do Capture for $200

6 Do Capture for $500

7 Authorization for $300

8 Do Capture for $150

9 Do Capture for $150

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Authorization, and Do Capture services. The following table lists the service calls for the

billing agreement scenarios.

Additional PayPal Express Checkout

Services

You can perform the services and functions described in the following table.

Table 9 Service Calls for Billing Agreement Scenarios

For a Billing Agreement

with Payment

For a Billing Agreement

without Payment

For a Reference

Transaction

1Set

2 Get Details

3 Do Payment

4 Do Capture

1 Set (for $0)

2 Get Details

3 Create Agreement

1 Do Reference Transaction

2 Authorization

3 Do Capture

Table 10 Additional PayPal Express Checkout Services

Service or Function Description

Reversal The Reversal service reverses an authorization or an order setup:

 For a regular order, sale, or immediate partial sale, simply call the

Reversal service.

 For a delayed authorization or delayed capture, you can reverse an

authorization or an order setup.

If you performed multiple authorizations and want to reverse one of

them, you must specify which authorization to reverse by

referencing the authorization ID.

After a capture has been made against an authorization, reversing

the authorization has no effect on the capture.

Full or partial refund The Refund service provides a credit to a customer. You can perform

multiple partial refunds for each capture:

 For a regular order, sale, or immediate partial sale, simply call the

Refund service.

 For a delayed authorization or delayed capture, you need to

specify which capture to credit.

Reauthorization

To reauthorize a transaction:

1 Reverse the authorization.

2 Perform a new authorization using the order ID.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Information About Your Transactions

The following table describes the methods you can use to obtain information about your

PayPal Express Checkout transactions.

Cancellation The Update Agreement service cancels a billing agreement ID, thus

cancelling the billing agreement. Use this service when a customer

notifies you that they no longer want you to bill their PayPal account.

Note When you call the Update Agreement service, Cybersource

cancels the billing agreement by calling the PayPal Update

Agreement service with a status of canceled.

Transaction Search The Transaction Search service returns information about one or

more transactions, as identified by a value associated with the

transaction, such as customer email address, date of transaction,

amount, transaction status, or invoice number.

Get Transaction Details The Get Transaction Details service returns information about a

transaction, as identified by a transaction identifier that was created

by PayPal.

Table 11 Methods of Obtaining Information About Your Transactions

Method Description

PayPal Express

Checkout services

The Transaction Search and Get Transaction Details services return

information about a transaction. See "Transaction Search Service,"

page 37, and "Get Transaction Details Service," page 38.

Reply messages After you send a request message for a PayPal Express Checkout service,

Cybersource responds with a reply message that contains information

about the status of your request, including errors and exceptions.

Reports Use the Business Center to view and download reports. The following daily

Cybersource reports include information about your PayPal Express

Checkout transactions:

 Payment Batch Detail Report

 Payment Batch Summary Report

 Payment Submission Detail Report

The Payment Batch Detail Report and Payment Submission Detail Report

are described in the Reporting Developer Guide. General information about

the reports are available in the online help for the Business Center. If you

are already subscribed to these reports, then you will automatically start to

see PayPal Express Checkout transactions in the reports. If you are a new

user of these reports, you can subscribe to the reports in the Business

Center.

Table 10 Additional PayPal Express Checkout Services (Continued)

Service or Function Description

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Disputes and Chargebacks

The following table describes the PayPal Express Checkout services related to disputes

and chargebacks.

Transaction

details

You can view the details of your PayPal Express Checkout transactions in

the Business Center just as you can for other payment types. You can

search for transactions by date, application type, consumer name, and

other transaction identifiers.

Table 12 Services for Disputes and Chargebacks

Service Description

Chargeback dispute rights If your customers choose a credit card as the funding source for

the PayPal Express Checkout payment, they have the normal

chargeback dispute rights. If your customers dispute a charge,

PayPal Express Checkout performs the initial chargeback

processing and contacts you for documentation.

Buyer complaint process PayPal Express Checkout offers a Buyer Complaint Process that

is applicable to all purchases regardless of the funding source.

When a customer files a complaint, PayPal investigates and

contacts you for documentation. See http://www.paypal.com/cgi-

bin/webscr?cmd=p/gen/buyer-complaint-outside.

Seller Protection Policy Cybersource supports the following Seller Protection Policy levels:

 Eligible: you are protected for unauthorized payments and

items not received.

 Partially eligible: you are protected for items not received.

 Ineligible: you are not protected.

PayPal offers additional features that are not currently supported

by Cybersource. See https://www.paypal.com/cgi-bin/

webscr?cmd=xpt/cps/securitycenter/sell/SellerPPOverview-

outside.

Table 11 Methods of Obtaining Information About Your Transactions (Continued)

Method Description

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Order Tracking

For general information about order tracking, see Getting Started with CyberSource

Advanced for the Simple Order API.

Reconciliation IDs and Transaction Reference

Numbers

Reconciliation IDs and transaction reference numbers are not supported for PayPal

Express Checkout.

Request IDs

For PayPal Express Checkout, all services are follow-on services except:

 The first call to the Set service

 Calls to the Cancellation (Update Agreement) service

 Calls to the Do Reference Transaction service

Request IDs in Reply Messages

For all PayPal Express Checkout services, the request ID is returned in the reply message

in requestID.

Request IDs in Request Messages

The following table lists the field names for the PayPal Express Checkout request IDs in

request messages.

Table 13 Request IDs in Request Messages

Service Field Names

Set payPalEcSetService_paypalEcSetRequestID

Get Details payPalEcGetDetailsService_paypalEcSetRequestID

Do Payment payPalEcDoPaymentService_paypalEcSetRequestID

Do Capture For a standard order:

payPalDoCaptureService_paypalEcDoPaymentRequestID

For a custom order:

payPalDoCaptureService_paypalAuthorizationRequestID

Order Setup payPalEcOrderSetupService_paypalEcSetRequestID

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the Simple Order API |

Authorization For a custom order:

payPalAuthorizationService_paypalEcOrderSetupRequestID

For a billing agreement:

payPalAuthorizationService_paypalDoRefTransactionRequestID

Create

Agreement

payPalCreateAgreementService_paypalEcSetRequestID

Authorization

Reversal

For a standard order:

payPalAuthReversalService_paypalEcDoPaymentRequestID

For a custom order when reversing an order setup:

payPalAuthReversalService_paypalEcOrderSetupRequestID

For a custom order when reversing an authorization:

payPalAuthReversalService_paypalAuthorizationRequestID

Refund payPalRefundService_paypalDoCaptureRequestID

Table 13 Request IDs in Request Messages (Continued)

Service Field Names

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 24

Requesting Services

Table 14 Request Services

Group General Service Name Simple Order API Service Name

Standard Orders Set Service payPalEcSetService

Get Details Service payPalEcGetDetailsService

Payment Service payPalEcDoPaymentService

Capture Service payPalDoCaptureService

Sale Service Multiple services

Custom Orders Set Service payPalEcSetService

Get Details Service payPalEcGetDetailsService

Order Setup Service payPalEcOrderSetupService

Authorization Service payPalAuthorizationService

Capture Service payPalDoCaptureService

Billing Agreements Set Service payPalEcSetService

Get Details Service payPalEcGetDetailsService

Payment Service payPalEcDoPaymentService

Capture Service payPalDoCaptureService

Create Agreement Service payPalCreateAgreementService

Reference Transaction Service payPalDoRefTransactionService

Authorization Service payPalAuthorizationService

Additional Services Authorization Reversal Service payPalAuthReversalService

Refund Service payPalRefundService

Reauthorization Service Multiple services

Cancellation Service payPalUpdateAgreementService

Transaction Search Service payPalTransactionSearchService

Get Transaction Details Service payPalGetTxnDetailsService

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

Set Service

The payPalEcSetService service:

 Alerts PayPal that an order is going to occur.

 Returns the PayPal token which is the token that identifies this session.

After payPalEcSetService returns, you must redirect your customer’s browser to the

PayPal web site.

Redirection URLs

PayPal has a specific URL for each of the two Express Checkout customer experience

flows.

Traditional Express Checkout Redirection URL

For Traditional Express Checkout, use the following URL and append the value of the

PayPal token:

https://www.paypal.com/cgibin/webscr?cmd=_express-

checkout&token=

Therefore, if the PayPal token is EC-4WL17777V4111184H, you will redirect this

customer’s browser to:

https://www.paypal.com/cgibin/webscr?cmd=_express-

checkout&token=EC-4WL17777V4111184H

For more information on Traditional Express Checkout, see "Traditional Express Checkout

Flow," page 12.

In-Context Express Checkout Redirection URL

For In-Context Express Checkout, use the following URL and append the value of the

PayPal token:

https://www.paypal.com/checkoutnow?&useraction=commit&token=

Therefore, if the PayPal Token is EC-4WL17777V4111184H, you will redirect this

customer’s browser to:

https://www.paypal.com/checkoutnow?&useraction=commit&token=EC-

4WL17777V4111184H

For more information on In-Context Express Checkout, see "In-Context Express Checkout

Flow," page 13.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

At the PayPal site, the customer can review and either approve or cancel the transaction.

If the customer approves the transaction, the customer is redirected to the return URL in

the field payPalEcSetServicePaypalReturn. If the customer cancels the transaction, the

customer is redirected to the return URL in the field payPalEcSetServicePaypalCancel

Return.

Multiple Calls to the Set Service

If, after the first call to payPalEcSetService, the customer realizes the shipping address is

incorrect, you can let the customer enter a different shipping address and then you can

call payPalEcSetService again as a follow-on service.

Required Fields

When you request payPalEcSetService, you must include the following fields in the

request:

 payPalEcSetService_run

 payPalEcSetService_paypalReturn

 payPalEcSetService_paypalCancelReturn

 merchantID

 merchantReferenceCode

 purchaseTotals_currency

The PayPal Sandbox URL for confirming CAS/Sandbox payments is:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_

express-checkout&token=

As with the production URL, you need to append your PayPal token to the end

of the URL.

If you are using Cybersource Decision Manager, do not allow customers to

change their shipping addresses in the PayPal portion of the session.

After each call to payPalEcSetService, you must redirect the customer’s

browser to the PayPal web page, appending the PayPal token to the URL listed

above.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

 purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field

For calls to payPalEcSetService after the first call, the following fields are also required:

 payPalEcSetService_paypalEcSetRequestID

 payPalEcSetService_paypalEcSetRequestToken

For calls to payPalEcSetService that initiate the creation of a billing agreement, include

the following fields:

 payPalEcSetService_paypalBillingType (required)

 payPalEcSetService_paypalBillingAgreementDesc (optional)

 payPalEcSetService_paypalBillingAgreementCustom (optional)

 payPalEcSetService_paypalPaymentType (optional)

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Get Details Service

The payPalEcGetDetailsService service:

 Returns information about a customer.

 Returns the billing agreement status if you initiated the creation of a billing agreement.

When calling payPalEcGetDetailsService, you can request the customer’s billing

address. When you do this, Cybersource returns the following fields in the reply message:

 payPalEcGetDetailsReply_street1

 payPalEcGetDetailsReply_street2

 payPalEcGetDetailsReply_city

 payPalEcGetDetailsReply_state

 payPalEcGetDetailsReply_postalCode

 payPalEcGetDetailsReply_countryCode

To enable item-level fields, contact Cybersource Customer Support to

have your account configured for this feature. For important information

about items and subtotals, see "Requirements for the Subtotal," page 38.

payPalEcGetDetailsService returns critical information necessary for order

processing. It is much easier to obtain this critical information through the API

rather than through an alternate method. Therefore, you must call

payPalEcGetDetailsService even if you do not allow customers to change

their shipping addresses.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

 payPalEcGetDetailsReply_countryName

 payPalEcGetDetailsReply_addressID

To receive these values, do the following:

 Contact your PayPal account manager to have this feature enabled on your PayPal

account.

 Contact Cybersource Customer Support to have your Cybersource account

configured to request the billing address.

 Set payPalEcSetService_requestBillingAddress to 1 in your request for

payPalEcSetService.

If you included item-level fields in your request for the payPalEcSetService service,

payPalEcGetDetailsService returns item-level fields in the reply message. These fields

are described in "Reply Field Descriptions," page 63.

When you request payPalEcGetDetailsService, you must include the following fields in

the request:

 payPalEcGetDetailsService_run

 payPalEcGetDetailsService_paypalToken

 payPalEcGetDetailsService_paypalEcSetRequestID

 payPalEcGetDetailsService_paypalEcSetRequestToken

 merchantID

 merchantReferenceCode

These fields are described in Appendix A, "API Fields," on page 41.

Payment Service

The payPalEcDoPaymentService service:

 Obtains the authorization implicitly.

 Returns an order ID and an authorization ID.

To enable item-level fields, contact Cybersource Customer Support to have

your account configured for this feature. For important information about items

and subtotals, see "Requirements for the Subtotal," page 38.

payPalEcDoPaymentService is used only for standard orders.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

 Returns a billing agreement ID if a billing agreement was created.

The Payment service sets an authorization as an embedded payment action parameter in

the third API call. When you use the Payment service, the authorization typically commits

funds for three business days. Contact PayPal to find out how to negotiate an honor

interval that is longer than three days. You can try to capture the authorization for a period

of 29 days after the authorization. If funds are still available, then the capture will be

successful.

When you request payPalEcDoPaymentService, you must include the following fields in

the request:

 payPalEcDoPaymentService_run

 payPalEcDoPaymentService_paypalToken

 payPalEcDoPaymentService_paypalPayerId

 payPalEcDoPaymentService_paypalEcSetRequestID

 payPalEcDoPaymentService_paypalEcSetRequestIToken

 payPalEcDoPaymentService_paypalCustomerEmail

 merchantID

 merchantReferenceCode

 purchaseTotals_currency

 purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field

When Decision Manager is enabled, you must also submit the following fields in the

request:

 billTo_city

 billTo_country

 billTo_postalCode—required only when billTo_country is set to US or CA.

 billTo_state—required only when billTo_country is set to US or CA.

 billTo_street1

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

To enable item-level fields, contact Cybersource Customer Support to

have your account configured for this feature. For important information

about items and subtotals, see "Requirements for the Subtotal," page 38.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

Order Setup Service

The payPalEcOrderSetupService service:

 Sets up an order in anticipation of one or more authorizations.

 Returns a transaction ID.

When you request payPalEcOrderSetupService, you must include the following fields in

the request:

 payPalEcOrderSetupService_run

 payPalEcOrderSetupService_paypalToken

 payPalEcOrderSetupService_paypalPayerId

 payPalEcOrderSetupService_paypalEcSetRequestID

 payPalEcOrderSetupService_paypalEcSetRequestToken

 payPalEcOrderSetupService_paypalCustomerEmail

 merchantID

 merchantReferenceCode

 purchaseTotals_currency

 purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Authorization Service

The payPalAuthorizationService service:

 Obtains the authorization.

 Enables you to perform multiple partial authorizations.

When you use the Authorization service, the authorization typically commits funds for

three business days. Contact PayPal to find out how to negotiate an honor interval that is

longer than three days. You can try to capture the authorization for a period of 29 days

after the authorization. If funds are still available, then the capture will be successful.

payPalEcOrderSetupService is used only for custom orders.

To enable item-level fields, contact Cybersource Customer Support to

have your account configured for this feature. For important information

about items and subtotals, see "Requirements for the Subtotal," page 38.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

When you request payPalAuthorizationService, you must include the following fields in

the request:

 payPalAuthorizationService_run

 payPalAuthorizationService_paypalOrderId

 payPalAuthorizationService_paypalCustomerEmail

 billTo_email

 merchantID

 merchantReferenceCode

 purchaseTotals_currency

 purchaseTotals_grandTotalAmount

 A request ID:

 For a custom order:

payPalAuthorizationService_paypalEcOrderSetupRequestID

 For a billing agreement:

payPalAuthorizationService_paypalDoRefTransactionRequestID

 A request token:

 For a custom order:

payPalAuthorizationService_paypalEcOrderSetupRequestToken

 For a billing agreement:

payPalAuthorizationService_paypalDoRefTransactionRequestToken

When Decision Manager is enabled, you must also submit the following fields in the

request:

 billTo_city

 billTo_country

 billTo_postalCode—required only when billTo_country is set to US or CA.

 billTo_state—required only when billTo_country is set to US or CA.

 billTo_street1

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

Capture Service

The payPalDoCaptureService service:

 Enables you to capture all of the authorized amount.

 Enables you to perform multiple partial captures, which are also called split shipments,

up to 115% of the authorized amount.

When you request payPalDoCaptureService, you must include the following fields in the

request:

 payPalDoCaptureService_run

 payPalDoCaptureService_completeType—This flag indicates whether it is a full

capture or a partial capture.

 payPalDoCaptureService_paypalAuthorizationId

 merchantID

 merchantReferenceCode

 purchaseTotals_currency

 purchaseTotals_grandTotalAmount

 A request ID:

 For a standard order: payPalDoCaptureService_paypalEcDoPaymentRequestID

 For a custom order: payPalDoCaptureService_paypalAuthorizationRequestID

 A request token:

 For a standard order: payPalDoCaptureService_

paypalEcDoPaymentRequestToken

 For a custom order: payPalDoCaptureService_paypalAuthorizationRequestToken

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Sale Service

A sale consists of calling payPalEcDoPaymentService and payPalDoCaptureService in

the same request. The sale:

 Obtains the authorization.

 Captures all of the authorized amount.

 Returns a transaction ID.

A capture transfers the funds from the customer’s account to your account.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

When you request payPalEcDoPaymentService and payPalDoCaptureService in the

same request, you must include the following fields in the request:

 payPalEcDoPaymentService_run

 payPalEcDoPaymentService_paypalCustomerEmail

 payPalEcDoPaymentService_paypalEcSetRequestID

 payPalEcDoPaymentService_paypalEcSetRequestIToken

 payPalEcDoPaymentService_paypalPayerId

 payPalEcDoPaymentService_paypalToken

 merchantID

 merchantReferenceCode

 purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field

 payPalDoCaptureService_run

 payPalDoCaptureService_completeType

 purchaseTotals_currency

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Create Agreement Service

The payPalCreateAgreementService service:

 Creates a billing agreement.

 Returns a billing agreement ID.

Before calling payPalCreateAgreementService:

 You must call payPalEcSetService for the amount of $0.

 The billing agreement status returned by the payPalEcGetDetailsService service

must indicate that the customer accepted the billing agreement.

When you request payPalCreateAgreementService, you must include the following

fields in the request:

 payPalCreateAgreementService_run

 payPalCreateAgreementService_paypalToken

 payPalCreateAgreementService_paypalEcSetRequestID

 payPalCreateAgreementService_paypalEcSetRequestToken

To enable item-level fields, contact Cybersource Customer Support to

have your account configured for this feature. For important information

about items and subtotals, see "Requirements for the Subtotal," page 38.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

 merchantID

 merchantReferenceCode

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Reference Transaction Service

The payPalDoRefTransactionService service uses a billing agreement to process a

payment.

When you request payPalDoRefTransactionService, you must include the following

fields in the request:

 merchantID

 merchantReferenceCode

 purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field

 purchaseTotals_currency

 payPalDoRefTransactionService_run

 payPalDoRefTransactionService_paypalBillingAgreementId

 payPalDoRefTransactionService_paypalPaymentType

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Authorization Reversal Service

The payPalAuthReversalService service releases the hold on a customer’s funds. The

following services can be reversed:

 payPalEcDoPaymentService

 payPalEcOrderSetupService

 payPalAuthorizationService

To enable item-level fields, contact Cybersource Customer Support to

have your account configured for this feature. For important information

about items and subtotals, see "Requirements for the Subtotal," page 38.

After a capture has been made against an authorization, reversing the

authorization has no effect on the capture.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

When you request payPalAuthReversalService, you must include the following fields in

the request:

 payPalAuthReversalService_run

 payPalAuthReversalService_paypalAuthorizationId

 merchantID

 merchantReferenceCode

 A request ID:

 For a standard order:

payPalAuthReversalService_paypalEcDoPaymentRequestID

 For a custom order when reversing an order setup:

payPalAuthReversalService_paypalEcOrderSetupRequestID

 For a custom order when reversing an authorization:

payPalAuthReversalService_paypalAuthorizationRequestID

 A request token:

 For a standard order:

payPalAuthReversalService_paypalEcDoPaymentRequestToken

 For a custom order when reversing an order setup:

payPalAuthReversalService_paypalEcOrderSetupRequestToken

 For a custom order when reversing an authorization:

payPalAuthReversalService_paypalAuthorizationRequestToken

These fields are described in Appendix A, "API Fields," on page 41.

Refund Service

The payPalRefundService service:

 Enables you to perform a full refund for an order.

 Enables you to perform multiple partial refunds for an order.

When you request payPalRefundService, you must include the following fields in the

request:

 payPalRefundService_run

 payPalRefundService_paypalCaptureId—This value determines which capture will be

refunded.

 payPalRefundService_paypalDoCaptureRequestID—This value determines which

capture will be refunded.

 payPalRefundService_paypalDoCaptureRequestToken

 merchantID

 merchantReferenceCode

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

 purchaseTotals_grandTotalAmount—The amount of the refund determines if it is a full

refund or a partial refund.

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Reauthorization Service

A reauthorization extends the honor period for an authorization. This is useful when an

authorization is about to expire.

Performing a Reauthorization

Step 1 Call payPalAuthReversalService.

Step 2 Call payPalEcDoPaymentService for a standard order or call the

payPalAuthorizationService for a custom order.

Cancellation Service

The payPalUpdateAgreementService service cancels a billing agreement.

When you request payPalUpdateAgreementService, you must include the following

fields in the request:

 payPalUpdateAgreementService_run

 payPalUpdateAgreementService_paypalBillingAgreementId

 payPalUpdateAgreementService_paypalBillingAgreementStatus

 merchantID

 merchantReferenceCode

Additional fields are optional. The required and optional fields are described in

Appendix A, "API Fields," on page 41.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

Transaction Search Service

Before requesting this service, you must:

 Contact Cybersource Customer Support to have your account configured for this

service.

 Enable your PayPal account for this service. See Step 13 in the procedure for setting

up a PayPal account, page 11.

The payPalTransactionSearchService service:

 Searches for transactions according to the search criteria in the request message.

 Returns information about the transactions that were found, up to a maximum of 100

transactions.

When you request payPalTransactionSearchService, you must include the following

fields in the request:

 payPalTransactionSearchService_run

 merchantID

 merchantReferenceCode

 payPalTransactionSearchService_startDate

 Fields for one or more of the search criteria in the following table:

Table 15 Transaction Search Criteria

Criteria Field Name

Customer’s email address payPalTransactionSearchService_

paypalCustomerEmail

Customer’s name: salutation payPalTransactionSearchService_payerSalutation

Customer’s name: first name payPalTransactionSearchService_payerFirstname

Customer’s name: middle name payPalTransactionSearchService_payerMiddlename

Customer’s name: last name payPalTransactionSearchService_payerLastname

Customer’s name: suffix payPalTransactionSearchService_payerSuffix

Date range payPalTransactionSearchService_endDate

The start date is specified in

payPalTransactionSearchService_startDate, which is

a required field for this service.

Invoice number payPalTransactionSearchService_invoiceNumber

Payment status payPalTransactionSearchService_paymentStatus

Receipt ID payPalTransactionSearchService_paypalReceiptId

Transaction amount payPalTransactionSearchService_grandTotalAmount

Transaction currency payPalTransactionSearchService_currency

Transaction ID payPalTransactionSearchService_transactionID

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

These fields are described in Appendix A, "API Fields," on page 41.

Get Transaction Details Service

Before requesting this service, you must:

 Contact Cybersource Customer Support to have your account configured for this

service.

 Enable your PayPal account for this service. See Step 13 in the procedure for setting

up a PayPal account, page 11.

The payPalGetTxnDetailsService service returns information about a transaction. When

you request payPalGetTxnDetailsService, you must include the transaction ID that was

returned by one of these services:

 payPalEcDoPaymentService

 payPalEcOrderSetupService

 payPalAuthorizationService

 payPalDoCaptureService

 payPalRefundService

 payPalDoRefTransactionService

When you request payPalGetTxnDetailsService, you must include the following fields in

the request:

 payPalGetTxnDetailsService_run

 payPalGetTxnDetailsService_transactionID

 merchantID

 merchantReferenceCode

These are described in Appendix A, "API Fields," on page 41.

Requirements for the Subtotal

A subtotal is the total amount for the products before taxes and shipping and handling

charges are added. The subtotal for a transaction must be greater than zero. If the

subtotal is less than or equal to zero, PayPal declines the transaction.

To calculate the subtotal, PayPal does the following:

1 Identifies the items for which the product code is not handling_only, shipping_and_

handling, or shipping_only.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the Simple Order API |

2 Multiplies quantity * unit price for each item identified in step 1.

3 Adds the values that were calculated in step 2.

Example 1 Items That Cause PayPal to Decline a Transaction (NVP)

item_0_unitPrice=10.00

item_0_quantity=1

item_0_productCode=Beverages

item_0_productName=Fancy Cola

item_0_productSKU=B4859

item_0_taxAmount=10

item_0_productDescription=Description for Fancy Cola!

item_1_unitPrice=5.00

item_1_productCode=shipping_only

item_2_unitPrice=10.00

item_2_quantity=1

item_2_productCode=coupon

item_2_productName=Discount

item_2_productSKU=D1000

item_2_productDescription=1000th customer discount

Example 2 Items That Cause PayPal to Decline a Transaction (XML)

<productCode>Beverages</productCode>

<productName>Fancy Cola</productName>

<productDescription>Description for Fancy Cola!</productDescription>

</item>

<productCode>shipping_only</productCode>

</item>

<productCode>coupon</productCode>

<productName>Discount</productName>

<productDescription>1000th customer discount!</productDescription>

</item>

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 41

API Fields

Formatting Restrictions

Unless otherwise noted, all of the field names listed are case sensitive, and the fields

accept special characters such as @, #, and %.

The values of the item_#_ fields must not contain carets (^) or colons (:), because these

characters are reserved for use by the ICS services. The values of all request fields must

not contain newlines or carriage returns. However, they can contain embedded spaces

and any other printable characters. All leading and trailing spaces are removed.

Data Type Definitions

For more information about these data types, see the World Wide Web Consortium (W3C)

XML Schema Part 2: Datatypes Second Edition.

Table 16 Data Type Definitions

Data Type Description

Date and time Format is YYYY-MM-DDThh:mm:ssZ, where:

 T separates the date and the time

 Z indicates Coordinated Universal Time (UTC), also known as Greenwich

Mean Time (GMT)

Example 2020-01-11T22:47:57Z equals January 11, 2020, at 22:47:57

(10:47:57 p.m.).

Integer Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}

String Sequence of letters, numbers, spaces, and special characters

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Numbered Elements

The CyberSource XML schema includes several numbered elements. You can include

these complex elements more than once in a request. For example, when a customer

order includes more than one item, you must include multiple <item> elements in your

request. Each item is numbered, starting with 0. The XML schema uses an id attribute in

the item’s opening tag to indicate the number. For example:

As a name-value pair field name, this tag is called item_0. In this portion of the field

name, the underscore before the number does not indicate hierarchy in the XML schema.

The item fields are generically referred to as item_#_<element name> in the

documentation.

Below is an example of the numbered <item> element and the corresponding name-

value pair field names. If you are using the Simple Object Access Protocol (SOAP), the

client contains a corresponding Item class.

Example 3 Numbered XML Schema Element Names and

Name-Value Pair Field Names

XML Schema

Element Names

Corresponding Name-Value

Pair Field Names

</item>

item_0_unitPrice

item_0_quantity

</item>

item_1_unitPrice

item_1_quantity

When a request in XML format includes an <item> element, the element must

include an id attribute. For example: <item id="0">.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Request Fields

Naming Conventions for Simple Order API Request

Fields

For most Simple Order API request fields, the field name that you use in your code must

be prefaced with the name of the service that is being called followed by an underscore

( _ ). In the following table, an asterisk (*) before a field name indicates that you should not

preface the field name with the service name.

Examples:

 Use this field to include the capture ID in a Refund service request

payPalRefundService_paypalCaptureId.

 Use this field to set the return URL in a Set service request payPalEcSetService_

paypalReturn.

The names of most Simple Order API request fields include a preface.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Request Field Descriptions

Some field descriptions come directly from PayPal and are not written by

Cybersource.

Table 17 Request Fields

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

billTo_city City of the billing address. payPalAuthorization

Service

payPalDoPayment

Service

Required only if

Decision Manager is

enabled.

String (50)

billTo_country Country of the billing address. Use the two-

character ISO Standard Country Codes.

payPalAuthorization

Service

payPalDoPayment

Service

Required only if

Decision Manager is

enabled.

String (2)

* billTo_email Customer’s email address. payPalAuthorization

Service (R)

String (256)

billTo_ipAddress Customer’s IP address. payPalAuthorization

Service (O)

String (45)

billTo_postalCode Postal code for the billing address. The postal

code must consist of 5 to 9 digits.

When the billing country is the U.S., the 9-digit

postal code must follow this format:

[5 digits][dash][4 digits]

Example 12345-6789

When the billing country is Canada, the 6-digit

postal code must follow this format:

[alpha][numeric][alpha][space]

[numeric][alpha][numeric]

Example A1B 2C3

payPalAuthorization

Service

payPalDoPayment

Service

Required only if

Decision Manager is

enabled AND the billing

country is US or

Canada.

String (10)

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

billTo_state State or province of the billing address. Use

the State, Province, and Territory Codes for the

United States and Canada.

payPalAuthorization

Service

payPalDoPayment

Service

Required only if

Decision Manager is

enabled AND the billing

country is US or

Canada.

String (2)

billTo_street1 First line of the billing street address. payPalAuthorization

Service

payPalDoPayment

Service

Required only if

Decision Manager is

enabled.

String (60)

completeType Indicates whether this is a partial capture or a

complete capture. Possible values:

 Complete: Complete capture

 NotComplete: Partial capture

payPalDoPayment

Service (R)

String (12)

currency Currency code for one of the PayPal

transactional currencies. See Appendix C,

"Currency Codes," on page 110.

Note PayPal can add currencies at any time.

For an up-to- list of currencies supported by

PayPal, contact your PayPal representative.

Important To request transactions in

currencies other than CNY for customers

located in China, contact Cybersource

Customer Support to have your account

configured for this functionality.

payPalTransaction

SearchService (O)

String (3)

endDate Date and time at which to end the search. The

date must be in UTC/GMT.

Format: YYYY-MM-DDTHH:MM:SSZ

Example 2012-09-15T17:23:15Z

payPalTransaction

SearchService (O)

String (20)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

grandTotalAmount Grand total for the entire order.

Format:

 Cannot include a currency symbol

 Must include two decimal places

 The decimal separator must be a period (.)

payPalTransaction

SearchService (O)

String (15)

invoiceNumber Your invoice or tracking number. This value

must be unique.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

payPalEcOrderSetup

Service (O)

payPalDoCapture

Service (O)

payPalDoRef

TransactionService (O)

payPalTransaction

SearchService (O)

String (127)

* item_#_productCode Type of product. You can set this field to a

value that you create or one of the predefined

values listed in Appendix D, "Product Codes,"

on page 111. The default value is

default.

If you set this field to a value other than

default or one of the shipping and handling

values, you must also include these item-level

fields in your request:

 product name

 product SKU

 quantity

See "Numbered Elements," page 42.

Note To enable item-level fields, contact

Cybersource Customer Support to have your

account configured for this feature.

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalDoRef

TransactionService

(See description)

String (255)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* item_#_

productDescription

For the log data to be complete, you must

include this field in requests that include item-

level fields. See "Numbered Elements,"

page 42.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

payPalEcOrderSetup

Service (O)

payPalDoRef

TransactionService (O)

String (127)

* item_#_productName This field is required if the product code is not

default or one of the shipping and handling

values. See "Numbered Elements," page 42.

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalDoRef

TransactionService

(See description)

String (127)

* item_#_productSKU Identification code for the product. This field is

required if the product code is not

default

or one of the shipping and handling values.

See "Numbered Elements," page 42.

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalDoRef

TransactionService

(See description)

String (127)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* item_#_quantity The default for this field is 1. This field is

required if the product code is not

default

or one of the shipping and handling values.

See "Numbered Elements," page 42.

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalDoRef

TransactionService

(See description)

Nonnegative

integer (10)

* item_#_taxAmount Total tax to apply to the product. This value

cannot be negative. The tax amount and the

unit price must be in the same currency. See

"Numbered Elements," page 42.

The tax amount field is additive. For example:

1 You send one item with a unit price of 10.00

and a tax amount of 0.80, and you send

another item with a unit price of 20.00 and a

tax amount of 1.60.

2 The total amount authorized will be 32.40,

not 30.00 with 2.40 of tax included.

If you want to include the tax amount and also

request the taxService service, see Tax

Calculation Service Using the Simple Order

API.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

payPalEcOrderSetup

Service (O)

payPalDoRef

TransactionService (O)

String (15)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* item_#_unitPrice Per-item price of the product. You must include

either this field or purchaseTotals_

grandTotalAmount in your request. See

"Numbered Elements," page 42. Also see the

information about items and grand totals in

Getting Started with CyberSource Advanced

for the Simple Order API.

This value must not exceed the equivalent of

10,000 USD in any currency. This value cannot

be negative.

Format:

 Cannot include a currency symbol

 Must include two decimal places

 The decimal separator must be a period (.)

Important If this value is less than or equal

to zero, PayPal declines the transaction.

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalDoRef

TransactionService

(See description)

String (15)

* 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 more information, see “Partial

Authorizations” in .

String (26) String (30)

* merchantID Your Cybersource merchant ID. Use the same

merchant ID for evaluation, testing, and

production.

Required for all PayPal

Express Checkout

services.

String (30)

* merchantReference

Code

Order reference number or tracking number

that you generate. Cybersource recommends

that you send a unique value for each

transaction so that you can perform meaningful

searches for the transaction. See the

information about tracking orders in Getting

Started with CyberSource Advanced for the

Simple Order API.

Required for all PayPal

Express Checkout

services

String (50)

payerFirstname Customer’s first name. payPalTransaction

SearchService (O)

String (25)

payerLastname Customer’s last name. payPalTransaction

SearchService (O)

String (25)

payerMiddlename Customer’s middle name. payPalTransaction

SearchService (O)

String (25)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

payerSalutation Customer’s salutation. payPalTransaction

SearchService (O)

String (20)

payerSuffix Customer’s suffix. payPalTransaction

SearchService (O)

String (12)

paymentStatus Possible values:

 Denied: You denied the payment. You can

deny a payment only if the payment was

pending.

 Pending: The payment is pending. To find

out why the payment is pending, request

payPalGetTxnDetailsService and look at

the value for the paypalPendingReason

field in the reply message.

 Processing: The payment is being

processed.

 Reversed: The payment was reversed as

the result of a chargeback or other type of

reversal. The funds were removed from

your account balance and returned to the

buyer.

 Success: The payment was completed

and the funds were successfully added to

your account balance.

payPalTransaction

SearchService (O)

String (20)

paypalAddress

Override

Customer-supplied address sent in the

SetExpressCheckout request rather than the

address on file with PayPal for this customer.

Note You can use this field only with the

payment method, not with the shortcut method.

See "Introduction to PayPal Express

Checkout," page 9, for a description of the

PayPal methods.

Possible values:

 1: Display the customer-supplied address.

 0 (default): Display the address on file with

PayPal. The customer cannot edit this

address.

payPalEcSetService

(O)

String (1)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalAuthorizationId Unique PayPal authorization identification

number.

For the payPalDoCaptureService, use the

number returned in the authorization reply in

the payPalAuthorizationReply_

transactionId field.

For payPalAuthReversalService, use the

number returned in the

payPalEcOrderSetupReply_transactionId

field.

payPalDoCapture

Service (R)

payPalAuthReversal

Service (R)

String (19)

paypalAuthorization

RequestID

Value of requestID returned from a previous

request for payPalAuthorizationService. This

is the requestID of the authorization you want

to capture or reverse.

If you request the authorization and capture

services together, you do not need to provide a

request ID for the capture request.

payPalDoCapture

Service

(See description)

payPalAuthReversal

Service

(See description)

String (26)

paypalAuthorization

RequestToken

Request token returned from a previous

Authorization request. This is the request

token from the authorization you want to

capture or reverse. If you request the

authorization and capture services together,

you do not need to provide a request token for

the capture request.

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.

payPalDoCapture

Service (R)

payPalAuthReversal

Service (R)

String (256)

paypalBilling

AgreementCustom

Custom annotation field for your own use. payPalEcSetService

(O for billing

agreements; otherwise,

not used)

payPalUpdate

AgreementService (O)

String (256)

paypalBilling

AgreementDesc

Description of the goods or services

associated with the billing agreement. PayPal

recommends that the description include a

brief summary of the billing agreement terms

and conditions.

Example 9.99 per month for 2 years.

payPalEcSetService

(O for billing

agreements; otherwise,

not used)

payPalUpdate

AgreementService (O)

Alphanumeric

String (127)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalBilling

AgreementId

Identifier for the billing agreement. payPalUpdate

AgreementService (R)

payPalDoRef

TransactionService (R)

String (256)

paypalBilling

AgreementStatus

Status of the billing agreement. Possible

values:

 Active: The billing agreement is active.

 Canceled: The billing agreement is

canceled.

payPalUpdate

AgreementService (R)

String (8)

paypalBillingType Type of billing agreement to create. The only

possible value is

MerchantInitiated

Billing

, which creates a billing agreement

for payments that you initiate.

payPalEcSetService

(R for billing

agreements; otherwise,

not used)

String (25)

paypalCancelReturn URL to which customers are returned if they do

not approve the use of PayPal for payment.

payPalEcSetService

(R)

String (no limit)

paypalCaptureId Unique PayPal transaction identification

number returned in the capture reply in the

payPalDoCaptureReply_transactionId field.

payPalRefundService

(R)

String (17)

paypalCustomerEmail Email address of the customer as entered

during checkout. PayPal uses this value to pre-

fill the PayPal membership sign-up portion of

the PayPal login page.

payPalEcSetService

(O)

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

payPalAuthorization

Service (R)

payPalTransaction

SearchService (O)

String (127)

paypalDesc Description of items the customer is

purchasing.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

payPalEcOrderSetup

Service (O)

payPalDoRef

TransactionService (O)

String (127)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalDoCapture

RequestID

Value of requestID returned from a previous

request for paypalDoCaptureService. When

calling payPalRefundService, this is the

requestID of the capture you want to credit.

payPalRefundService

(R)

String (26)

paypalDoCapture

RequestToken

Request token returned from a previous Do

Capture request. This is the request token

from the capture you want to credit.

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.

payPalRefundService

(R)

String (256)

paypalDoRef

TransactionRequestID

Value of requestID returned from a previous

request for payPalDoRefTransactionService.

payPalAuthorization

Service (R)

String (26)

paypalDoRef

TransactionRequest

Token

Request token returned from a previous Do

Reference Transaction request.

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.

payPalAuthorization

Service (R)

String (256)

paypalEcDoPayment

RequestID

Value of requestID returned from a previous

request for payPalEcDoPaymentService.

This is the requestID of the payment you want

to capture or reverse.

If you request the payment and capture

services together, you do not need to provide a

request ID for the capture request.

payPalDoCapture

Service

(See description)

payPalAuthReversal

Service

(See description)

String (26)

paypalEcDoPayment

RequestToken

Request token returned from a previous Do

Payment request. This is the request token

from the payment you want to capture or

reverse. If you request the payment and

capture services together, you do not need to

provide a request token for the capture

request.

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.

payPalDoCapture

Service (R)

payPalAuthReversal

Service (R)

String (256)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalEcNotifyUrl URL to which your Instant Payment

Notification (IPN) is sent. If you do not include

this value, the notification URL in your

merchant account will be used, if one exists.

payPalDoRef

TransactionService (O)

Alphanumeric

(2048)

paypalEcOrderSetup

RequestID

Value of requestID returned from a previous

request for payPalEcOrderSetupService.

This is the requestID of the order setup you

want to authorize or reverse.

payPalAuthorization

Service (R)

payPalAuthReversal

Service

(See description)

String (26)

paypalEcOrderSetup

RequestToken

Request token returned from a previous Order

Setup request. This is the request token from

the order setup you want to authorize or

reverse.

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.

payPalAuthorization

Service (R)

payPalAuthReversal

Service (R)

String (256)

paypalEcSetRequestID Value of requestID returned from a previous

request for payPalEcSetService.

payPalEcSetService

(Required unless it is

the first call to

payPalEcSetService)

payPalEcGetDetails

Service (R)

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

payPalCreate

AgreementService (R)

String (26)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalEcSetRequest

Token

Request token returned from a previous Set

request.

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.

payPalEcSetService

(Required unless it is

the first call to

payPalEcSetService)

payPalEcGetDetails

Service (R)

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

payPalCreate

AgreementService (R)

String (256)

paypalHdrbackcolor Background color for the header of the

payment page.

Format: HTML hexadecimal color

payPalEcSetService

(O)

String (6)

paypalHdrbordercolor Border color around the header of the payment

page.

Format: HTML hexadecimal color

payPalEcSetService

(O)

String (6)

paypalHdrimg URL for the image that will be displayed in the

upper left area of the payment page.

payPalEcSetService

(O)

String (127)

paypalLc Locale of pages displayed by PayPal during

Express Checkout.

Possible values:

 AU: Australia

 DE: Germany

 ES: Spain

 FR: France

 GB: United Kingdom

 IT: Italy

 US (default): United States

payPalEcSetService

(O)

String (2)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalLogoimg URL for an image that PayPal displays on the

payment form. This field enables you to add

your logo or other image to the PayPal

payment form.

If you provide this value and paypalHdrimg in

your request, PayPal uses this value and

ignores paypalHdrimg.

Note Contact Cybersource Customer

Support to have your account configured for

this feature.

payPalEcSetService

(O)

String (127)

paypalMaxamt Expected maximum total amount of the entire

order, including shipping costs and tax

charges. This value must not exceed the

equivalent of 10,000 USD in any currency.

Format:

 Cannot include a currency symbol

 Must include two decimal places

 The decimal separator must be a period (.)

payPalEcSetService

(O)

String (15)

paypalNoshipping Indicates whether the shipping address should

be displayed on the PayPal

web pages.

Possible values:

 0 (default): Shipping address fields should

be displayed.

 1: Shipping address fields should not be

displayed.

payPalEcSetService

(O)

String (1)

paypalNote Memo about the refund. PayPal sends this

information to the customer in the notification

email.

payPalRefundService

(O)

String (255)

paypalOrderId Transaction identifier created by PayPal. This

field is returned:

 For a standard order: In the

payPalEcDoPaymentReply_transactionId

in the reply from

payPalEcDoPaymentService.

 For a custom order: In the

payPalEcOrderSetupReply_transactionId

in the reply from

payPalEcOrderSetupService.

payPalAuthorization

Service (O)

String (255)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalPagestyle Sets the Custom Payment Page Style for

payment pages associated with this button or

link. This value corresponds to the HTML

variable page_style for customizing payment

pages. The value is the same as the Page

Style Name you choose when adding or editing

the page style from the Profile tab of the My

Account tab of your PayPal account.

payPalEcSetService

(O)

Alphabetic

String (30)

paypalPayerId Unique PayPal customer account identification

number that was returned in the

payPalEcGetDetailsService reply message.

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

String (13)

paypalPayflowcolor Background color for the payment page.

Format: HTML hexadecimal color

payPalEcSetService

(O)

String (6)

paypalPaymentType Indicates whether the payment is instant or

delayed. Possible values:

 echeck

 instant

paypalEcSetService

(O for billing

agreements; otherwise,

not used)

payPalDoRef

TransactionService (R)

String (7)

paypalReceiptId Receipt identification number.

Format: NNNN-NNNN-NNNN-NNNN

payPalTransaction

SearchService (O)

String (16)

paypalReqconfirm

shipping

Indicates if you require the customer’s shipping

address on file with PayPal to be a confirmed

address. Possible values:

 0 (default): Shipping address need not be

confirmed.

 1: Shipping address must be confirmed.

payPalEcSetService

(O)

payPalDoRef

TransactionService (O)

String (1)

paypalReturn URL to which the customer’s browser returns

after leaving PayPal.

Note It is essential that this be the correct

URL or you will receive an error.

payPalEcSetService

(R)

String (no limit)

paypalReturnFmf

Details

Indicates whether or not to return to you the

results that were returned by Fraud

Management Filters (FMF). By default, you do

not receive this information. Possible values:

 0 (default): Do not return FMF results.

 1: Return FMF results.

payPalDoRef

TransactionService (O)

String (1)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalShipping

Discount

Shipping discount for the order. This value:

 Must not exceed the equivalent of 10,000

USD in any currency.

 Cannot include a currency symbol.

If a decimal separator is used, it must be a

period (.) regardless of the currency. If a

thousands separator is used, it must be a

comma (,) regardless of the currency.

payPalDoRef

TransactionService (O)

String (9)

paypalSoftDescriptor Description that is displayed on the customer’s

account statement.

payPalDoRef

TransactionService (O)

String (256)

paypalToken Timestamped token by which you identify to

PayPal that you are processing this payment

with Express Checkout. This value is returned

by payPalEcSetService the first time you

request the service.

payPalEcSetService

(Required unless it is

the first call to

payPalEcSetService)

payPalEcGetDetails

Service (R)

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

payPalCreate

AgreementService (R)

String (20)

promoCode0 Promotion code that enables customers to

apply PayPal promotions to your products

when purchased through PayPal Express

Checkout.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

payPalEcOrderSetup

Service (O)

String (20)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* purchaseTotals_

currency

Currency code for one of the PayPal

transactional currencies. See Appendix C,

"Currency Codes," on page 110.

Note PayPal can add currencies at any time.

For an up-to- list of currencies supported by

PayPal, contact your PayPal representative.

Important To request transactions in

currencies other than CNY for customers

located in China, contact Cybersource

Customer Support to have your account

configured for this functionality.

payPalEcSetService

(R)

payPalEcDoPayment

Service (R)

payPalEcOrderSetup

Service (R)

payPalAuthorization

Service (R)

payPalDoCapture

Service (R)

payPalDoRef

TransactionService (R)

String (3)

* purchaseTotals_

grandTotalAmount

Grand total for the entire order. If you know the

shipping costs and tax amounts, include them

in this value. If you do not know the shipping

costs and tax amounts, this value should be

the subtotal for the order. This value must not

exceed the equivalent of 10,000 USD in any

currency. This value cannot be negative.

For payPalEcSetService, payPalEcDo

PaymentService, payPalEcOrderSetup

Service, and payPalDoRefTransaction

Service, the request must include either this

field or item_0_unitPrice. See the information

about items and grand totals in Getting Started

with CyberSource Advanced for the Simple

Order API.

Format:

 Cannot include a currency symbol

 Must include two decimal places

 The decimal separator must be a period (.)

payPalEcSetService

(See description)

payPalEcDoPayment

Service

(See description)

payPalEcOrderSetup

Service

(See description)

payPalAuthorization

Service (R)

payPalDoCapture

Service (R)

payPalRefundService

(R)

payPalDoRef

TransactionService

(See description)

String (15)

requestBillingAddress Indicates whether to return the customer’s

billing address when you call

payPalEcGetDetailsService. Possible values:

 0: Do not return the customer’s billing

address.

 1: Return the customer’s billing address.

payPalEcSetService

(O)

String (1)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

run Indicates whether to include the service in your

request. Possible values:

 true: Include the service in your request.

 false (default): Do not include the service

in your request.

Required for all PayPal

Express Checkout

Services

String (5)

* shipTo_city City of the shipping address. payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (40)

* shipTo_country Country of the shipping address. Use the two-

character ISO Standard Country Codes.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (2)

* shipTo_firstName First name of the recipient. payPalEcDoPayment

Service (O)

payPalEcSetService

(O)

String (15)

* shipTo_lastName Last name of the recipient. payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (15)

* shipTo_phone

Number

Phone number for the shipping address. payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (20)

* shipTo_postalCode Postal code for the shipping address. The

postal code must consist of 5 to 9 digits.

When the shipping country is the U.S., the 9-

digit postal code must follow this format:

[5 digits][dash][4 digits]

Example 12345-6789

When the shipping country is Canada, the 6-

digit postal code must follow this format:

[alpha][numeric][alpha][space]

[numeric][alpha][numeric]

Example A1B 2C3

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (20)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* shipTo_state State or province of the shipping address. Use

the State, Province, and Territory Codes for the

United States and Canada.

payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (40)

* shipTo_street1 First line of the shipping address. payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (100)

* shipTo_street2 Second line of the shipping address. payPalEcSetService

(O)

payPalEcDoPayment

Service (O)

String (100)

startDate Date and time at which to start the search. The

date must be in UTC/GMT.

Format: YYYY-MM-DDTHH:MM:SSZ

Example 2012-08-15T17:23:15Z

payPalTransaction

SearchService (R)

String (20)

transactionID Value of transactionId returned from a

previous request. This is the transactionId of

the transaction for which you are requesting

information.

payPalTransaction

SearchService (O)

payPalGetTxnDetails

Service (R)

String (17)

Table 17 Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Request Fields," page 42.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Reply Fields

Naming Conventions for Simple Order API Reply

Fields

For most Simple Order API reply fields, the field name that you use in your code must

include a preface followed by an underscore ( _ ). The following table lists the Simple

Order API services and the preface to use for each service. In Tab le 19, an asterisk (*)

before a field name indicates that you should not preface the field name.

Examples:

 The Do Capture service returns the receipt ID in payPalDoCaptureReply_

paypalReceiptId.

 The Get Details service returns the shipping country in payPalEcGetDetailsReply_

shipToCountry.

The names of most Simple Order API reply fields include a preface.

Table 18 Prefaces for Simple Order API Reply Fields

Service Name Preface

payPalAuthorizationService payPalAuthorizationReply

payPalAuthReversalService payPalAuthReversalReply

payPalCreateAgreementService payPalCreateAgreementReply

payPalDoCaptureService payPalDoCaptureReply

payPalDoRefTransactionService payPalDoRefTransactionReply

payPalEcDoPaymentService payPalEcDoPaymentReply

payPalEcGetDetailsService payPalEcGetDetailsReply

payPalEcOrderSetupService payPalEcOrderSetupReply

payPalEcSetService payPalEcSetReply

payPalGetTxnDetailsService payPalGetTxnDetailsReply

payPalRefundService payPalRefundReply

payPalTransactionSearchService payPalTransactionSearchReply

payPalUpdateAgreementService payPalUpdateAgreementReply

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Reply Field Descriptions

In the following table, an asterisk (*) before a field name indicates that you should not

preface the field name.

Some field descriptions come directly from PayPal and are not written by

Cybersource.

Table 19 Reply Fields

Field Description Returned By Data Type &

Length

addressID eBay company that maintains this address.

Possible values:

 eBay

 PayPal

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (20)

addressStatus Status of the street address on file with

PayPal. Possible values:

 None

 Confirmed

 Unconfirmed

payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (12)

amount Total transaction amount. payPalEcSetService

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalAuthorization

Service

payPalDoCapture

Service

String (15)

authorizationId Authorization identification number that was

sent in the request.

payPalDoCapture

Service

payPalAuthReversal

Service

String (19)

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

avsCode Indicates the status of the customer’s

address. Possible values:

 1: None

 2: Other

 3: Confirmed

 4: Unconfirmed

payPalEcGetDetails

Service

Numeric (1)

city City in the customer’s billing address. payPalEcGetDetails

Service

String (40)

correlationID Identifier that can be used for working with

PayPal to investigate issues.

All PayPal Express

Checkout services

String (20)

countryCode Code for the country in the customer’s billing

address.

payPalEcGetDetails

Service

String (2)

countryName Name of the country in the customer’s billing

address.

payPalEcGetDetails

Service

String (40)

currency Currency code for one of the PayPal

transactional currencies. See Appendix C,

"Currency Codes," on page 110.

Note PayPal can add currencies at any time.

For an up-to-date list of currencies supported

by PayPal, contact your PayPal

representative.

payPalEcSetService

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalAuthorization

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (3)

* decision Summarizes the result of the overall request.

See the information about handling replies in

Getting Started with CyberSource Advanced

for the Simple Order API. Possible values:

 ACCEPT

 ERROR

 REJECT

 REVIEW

All PayPal Express

Checkout services

String (6)

errorCode Identifier that can be used for working with

PayPal to investigate issues.

All PayPal Express

Checkout services

String (10)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* 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 for the Simple

Order API.

All PayPal Express

Checkout services

String (100)

* item_#_productCode Type of product. Possible values:

 coupon

 default

 handling_only

 shipping_and_handling

Note

The shipping_only line items are

not returned. Instead, their amount values are

added to the s

hipping_and_handling

line item.

Note If you use a customized value for the

product code, you receive a value of

default in this field.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (255)

* item_#_

productDescription

The product description is not returned when

the product code is

handling_only or

shipping_and_handling.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (127)

* item_#_productName The product name is not returned when the

product code is

handling_only or

shipping_and_handling.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (127)

* item_#_productSKU Identification code for the product. payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (127)

* item_#_quantity The quantity is not returned when the product

code is

handling_only or shipping_

and_handling

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

Nonnegative

integer (10)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* item_#_unitPrice Per-item price of the product. payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (15)

* merchantReference

Code

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.

All PayPal Express

Checkout services

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 Started

with CyberSource Advanced for the Simple

Order API.

All PayPal Express

Checkout services

String (100)

orderId Transaction identifier created by PayPal. payPalEcDoPayment

Service

String (255)

parentTransactionId Identifier for the original transaction to which

this transaction is related. Field populated for:

 Authorization of an order

 Capture of an authorized transaction

 Capture of an order

 Capture of an order authorization

 Reauthorization of a transaction

 Reversal

 Void of an order

Format: NNNN-NNNN-NNNN-NNNN

payPalDoCapture

Service

payPalGetTxnDetails

Service

String (19)

payer Customer’s email address. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (127)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

payerBusiness Customer’s business name. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (127)

payerCountry Country to ship the product to. Use the two-

character ISO Standard Country Codes.

payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (2)

payerFirstname Customer’s first name. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (25)

payerId Customer’s unique PayPal account

identification number.

payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (13)

payerLastname Customer’s last name. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (25)

payerMiddlename Customer’s middle name. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (25)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

payerPhone Customer’s contact telephone number.

Field mask for U.S. numbers:

XXX-XXX-XXXX

Field mask for international numbers:

+XXX XXXXXXXX

payPalEcGetDetails

Service

String (20)

payerSalutation Customer’s salutation. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (20)

payerStatus Customer’s status. Possible values:

 verified

 unverified

payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (10)

payerSuffix Customer’s suffix. payPalEcGetDetails

Service

payPalUpdate

AgreementService

payPalGetTxnDetails

Service

String (12)

paymentType Indicates whether the payment is instant or

delayed. Possible values:

 none

 echeck

 instant

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

String (7)

paypalAmount Final amount charged. payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalAuthorization

Service

payPalDoRef

TransactionService

String (15)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalBilling

AgreementAccepted

Status

Indicates if the customer accepted the billing

agreement. Possible values:

 0: Not accepted

 1: Accepted

payPalEcGetDetails

Service

String (1)

paypalBilling

AgreementCustom

Custom annotation field. payPalUpdate

AgreementService

String (256)

paypalBilling

AgreementDesc

Description of the goods or services

associated with the billing agreement.

payPalUpdate

AgreementService

String (127)

paypalBilling

AgreementId

Identifier for the billing agreement. payPalCreate

AgreementService

payPalEcDoPayment

Service

payPalUpdate

AgreementService

payPalDoRef

TransactionService

String (256)

paypalBilling

AgreementStatus

Status of the billing agreement. Possible

values:

 Active: The billing agreement is active.

 Canceled: The billing agreement has

been cancelled.

payPalUpdate

AgreementService

String (8)

paypalExchangeRate Exchange rate if a currency conversion

occurred.

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (17)

paypalFeeAmount PayPal fee charged for the transaction. This

value does not exceed the equivalent of

10,000 USD in any currency and does not

include a currency symbol. The decimal

separator is a period (.) and the optional

thousands separator is a comma (,).

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalGetTxnDetails

Service

String (9)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalFeeRefund

Amount

Amount of PayPal fee refunded if the capture

was refunded. This value does not exceed the

equivalent of 10,000 USD in any currency and

does not include a currency symbol. The

decimal separator is a period (.) and the

optional thousands separator is a comma (,).

payPalRefundService String (9)

paypalGrossRefund

Amount

Amount of money refunded to the customer. payPalRefundService Ask your

PayPal

representative

invoiceNumber Your invoice or tracking number. payPalGetTxnDetails

Service

String (127)

paypalNetRefund

Amount

Amount subtracted from PayPal balance of

the customer who is getting the refund.

payPalRefundService Ask your

PayPal

representative

paypalNote Memo or note that the customer entered on

the PayPal pages.

payPalGetTxnDetails

Service

String (255)

paypalOrderTime Date-time stamp of the payment.

Format: YYYY-MM-DDTHH:MM:SSZ

Example 2012-08-15T17:23:15Z

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (20)

paypalPaymentGross

Amount

Final amount charged including shipping

costs and taxes from your PayPal Merchant

Profile. This value does not exceed the

equivalent of 10,000 USD in any currency and

does not include a currency symbol. The

decimal separator is a period (.) and the

optional thousands separator is a comma (,).

payPalDoCapture

Service

payPalGetTxnDetails

Service

Ask your

PayPal

representative

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalPaymentStatus Status of the transaction. Possible values:

 Canceled-Reversal: PayPal

canceled the reversal, which happens

when you win a dispute and the funds for

the reversal are returned to you.

 Completed: PayPal completed the

payment and added the funds to your

account.

 Denied: You denied a payment, which

happens only if the payment was pending

for the reason indicated in the

paypalPendingReason field.

 Expired: The authorization expired.

 Failed: The payment failed. This event

can happen only when the payment is

made from your customer’s bank account.

 In-Progress: The transaction has not

been completed yet.

 None: No status.

 Partially-Refunded: The payment

was partially refunded.

 Pending: The payment is pending for the

reason indicated in the paypalPending

Reason field.

 Processed: PayPal accepted the

payment.

 ReasonCode

 Refunded: You refunded the payment.

 Reversed: PayPal reversed the payment

for the reason specified in the paypal

ReasonCode field. The funds were

transferred from your account to the

customer’s account.

 Voided: The authorization was voided.

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (20)

paypalPaymentType Indicates whether the payment is instant or

delayed. Possible values:

 none

 echeck

 instant

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (7)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalPendingReason Indicates the reason that payment is\ pending.

Possible values:

 address: Your customer did not include a

confirmed shipping address and your

Payment Receiving Preferences are set to

manually accept or deny such payments.

To change your preferences, go to the

Preferences section of your PayPal Profile.

 authorization: The payment has

been authorized but not settled. You need

to capture the authorized amount.

 echeck: Payment was made by an

eCheck that has not yet cleared.

 intl: You have a non-U.S. account and

do not have a withdrawal mechanism. You

must manually accept or deny this payment

in your PayPal Account Overview.

 multi-currency: You do not have a

balance in the currency sent, and your

Payment Receiving Preferences are not

set to automatically convert and accept this

payment. You must manually accept or

deny this payment in your PayPal Account

Overview.

 none: No pending reason.

 order: The payment is part of an order

that has been authorized but not settled.

 paymentreview: The payment is being

reviewed by PayPal for possible fraud.

 unilateral: The payment was made to

an email address that is not registered or

confirmed.

 verify: Your account is not yet verified.

You must verify your account before you

can accept this payment.

 other: Payment is pending for a reason

not listed above. For more information,

contact PayPal customer service.

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

Note To enable the

paypalPendingReason

field for payPalDo

CaptureService,

contact Cybersource

Customer Support to

have your account

configured for this

feature.

String (14)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalReasonCode Indicates the reason for a transaction

reversal. Possible values:

 buyer-complaint: Your customer

submitted a complaint about the

transaction.

 chargeback: Your customer initiated a

chargeback for this transaction.

 guarantee: Your customer triggered a

money-back guarantee.

 none: No reason code.

 refund: You gave the customer a refund.

 other: A reversal has occurred on this

transaction due to a reason not listed

above. For more information, contact

PayPal customer service.

payPalEcOrderSetup

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (15)

paypalReceiptId Receipt identification number.

Format: NNNN-NNNN-NNNN-NNNN

payPalDoCapture

Service

payPalGetTxnDetails

Service

String (16)

paypalSettleAmount Amount deposited in your PayPal account

after a currency conversion. This value does

not exceed the equivalent of 10,000 USD in

any currency and does not include a currency

symbol. The decimal separator is a period (.)

and the optional thousands separator is a

comma (,).

payPalGetTxnDetails

Service

String (15)

paypalTaxAmount Tax charged on the transaction. This value

does not exceed the equivalent of 10,000

USD in any currency and does not include a

currency symbol. The decimal separator is a

period (.) and the optional thousands

separator is a comma (,).

payPalEcDoPayment

Service

payPalEcGetDetails

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (9)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

paypalToken Timestamped token by which you identify to

PayPal that you are processing this payment

with Express Checkout. You need to save this

value to send in future request messages.

payPalEcSetService

payPalEcGetDetails

Service

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

String (20)

paypalTransaction

type

Type of transaction. Possible values:

 cart

 express-checkout

payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalDoCapture

Service

payPalGetTxnDetails

Service

String (16)

paypalTransaction

Type

Note For

PayPalDoRef

TransactionService,

the last four letters of

this field name start with

an uppercase “T,” but for

the other PayPal

Express Checkout

services, the last four

letters of this field name

start with a lowercase

“t.”

Type of transaction. Possible values:

 cart

 express-checkout

payPalDoRef

TransactionService

String (16)

postalCode Postal code in the customer’s billing address. payPalEcGetDetails

Service

String (20)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

protectionEligibility Seller protection in force for the transaction.

Possible values:

 Eligible: You are protected by the

PayPal Seller Protection Policy for

unauthorized payment and item not

received.

 PartiallyEligible: You are

protected by the PayPal Seller Protection

Policy for item not received.

 Ineligible: You are not protected

under the PayPal Seller Protection Policy.

PayPal offers additional features that are not

currently supported by Cybersource.

payPalAuthorization

Service

payPalGetTxnDetails

Service

String (17)

protectionEligibilityType Seller protection in force for the transaction.

Possible values:

 Eligible: You are protected by the

PayPal Seller Protection Policy for

unauthorized payment and item not

received.

 ItemNotReceivedEligible: You

are protected by the PayPal Seller

Protection Policy for item not received.

 UnauthorizedPaymentEligible:

You are protected by the PayPal Seller

Protection Policy for unauthorized

payment.

 Ineligible: You are not protected

under the PayPal Seller Protection Policy.

Note To enable the protectionEligibility

Type field, contact Cybersource Customer

Support to have your account configured for

this feature.

payPalAuthorization

Service

payPalGetTxnDetails

Service

String (32)

reasonCode Numeric value corresponding to the result of

the service request. See Appendix E,

"Reason Codes," on page 112.

All PayPal Express

Checkout services

Integer (5)

* reasonCode Numeric value corresponding to the result of

the overall request. See Appendix E, "Reason

Codes," on page 112.

All PayPal Express

Checkout services

Integer (5)

* requestID Identifier for the request generated by the

client.

All PayPal Express

Checkout services

String (26)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

* requestToken Request token data created by CyberSource

for each reply. You need to store the contents

of this field so that you can retrieve and send

it in follow-on requests. This value is an

encoded string that contains no confidential

information, such as an account number or

card verification number. The string can

contain up to 256 characters.

If you request the Authorization and Capture

services together, the request token is for the

capture reply only.

See the information about request tokens in

Getting Started with CyberSource Advanced

for the Simple Order API.

All PayPal Express

Checkout services

String (256)

shipToAddress1 First line of the shipping address. payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (100)

shipToAddress2 Second line of the shipping address. payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (100)

shipToCity City of the shipping address. payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (40)

shipToCountry Country of the shipping address. Use the two-

character ISO Standard Country Codes.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (2)

shipToName Name of the recipient. payPalGetTxnDetails

Service

String (32)

shipToPhone Phone number for the shipping address. payPalGetTxnDetails

Service

String (20)

shipToState State or province of the shipping address. Use

the State, Province, and Territory Codes for

the United States and Canada.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (40)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

shipToZip Postal code for the shipping address.

Consists of 5 to 9 digits.

payPalEcGetDetails

Service

payPalGetTxnDetails

Service

String (20)

state Abbreviation for the state or province in the

customer’s billing address.

payPalEcGetDetails

Service

String (40)

street1 First line of the street address in the

customer’s billing address.

payPalEcGetDetails

Service

String (100)

street2 Second line of the street address in the

customer’s billing address.

payPalEcGetDetails

Service

String (100)

transactionId Unique PayPal identifier for the transaction. payPalEcDoPayment

Service

payPalEcOrderSetup

Service

payPalAuthorization

Service

payPalDoCapture

Service

payPalRefundService

payPalDoRef

TransactionService

payPalGetTxnDetails

Service

String (17)

Table 19 Reply Fields (Continued)

Field Description Returned By Data Type &

Length

* Do not preface this field with part of the service name. See "Naming Conventions for Simple Order API Reply Fields," page 61.

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

Transaction Search Reply Fields

The payPalTransactionSearchService service returns information about transactions,

up to a maximum of 100 transactions. The transactions are referred to as transaction_0,

transaction_1, transaction_2, and so on.

For the transaction search reply fields, the field name that you use in your code

must include a preface followed by an underscore ( _ ). The preface to use is

payPalTransactionSearchReply. For example, the Transaction Search

service returns the first transaction’s currency in payPalTransactionSearch

Reply_transaction_0_currency. "Transaction Search Example," page 92,

and "Transaction Search Example," page 108, show what the transaction

search reply fields look like in a reply message.

Table 20 Transaction Search Reply Fields

Field Description Returned By Data Type

& Length

transaction_#_

currency

Currency code for the transaction. See Appendix C,

"Currency Codes," on page 110.

payPalTransaction

SearchService

String (3)

transaction_#_

customer

DisplayName

Customer’s name as displayed on the PayPal web

pages.

payPalTransaction

SearchService

String

transaction_#_

grandTotal

Amount

Total transaction amount. payPalTransaction

SearchService

String (15)

transaction_#_

paypalFee

Amount

Fee that PayPal charged for the transaction. payPalTransaction

SearchService

Decimal

transaction_#_

paypalNet

Amount

Net amount of the transaction. payPalTransaction

SearchService

Decimal

transaction_#_

paypalPayerOr

PayeeEmail

If the payment amount is positive, this field is the email

address of the payment recipient (the “payee”). If the

payment is negative, this field is the email address of

the customer.

payPalTransaction

SearchService

String (127)

Chapter API Fields

PayPal Express Checkout Services Using the Simple Order API |

transaction_#_

paypalPayment

Status

Possible values:

 Denied: You denied the payment. You can deny a

payment only if the payment was pending.

 Pending: The payment is pending. To find out

why the payment is pending, request the ics_

paypal_get_txn_details service and look at the

value for the paypal_pending_reason field in the

reply message.

 Processing: The payment is being processed.

 Reversed: The payment was reversed as the

result of a chargeback or other type of reversal.

The funds were removed from your account

balance and returned to the buyer.

 Success: The payment was completed and the

funds were successfully added to your account

balance.

payPalTransaction

SearchService

String (20)

transaction_#_

transactionID

Unique PayPal identifier for the transaction. payPalTransaction

SearchService

String (17)

transaction_#_

transaction

Time

Date and time when PayPal processed the

transaction. This value is in UTC/GMT.

Format: YYYY-MM-DDTHH:MM:SSZ

Example 2012-09-12T17:23:15Z

payPalTransaction

SearchService

String (20)

transaction_#_

transaction

Timezone

Time zone for the transaction_#_paypal_

transaction_time value. This value is always GMT.

payPalTransaction

SearchService

String (3)

transaction_#_

transaction

Type

Possible values:

 Currency Conversion (credit)

 Currency Conversion (debit)

 Payment

 Recurring Payment

 Temporary Hold

 Transfer

 Donation

payPalTransaction

SearchService

String (16)

Table 20 Transaction Search Reply Fields (Continued)

Field Description Returned By Data Type

& Length

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 80

Examples

Name-Value Pair Examples

Billing Agreement Examples

Billing Agreement with Payment

This example shows how to create a billing agreement with payment by calling these

services:

 payPalEcSetService

 payPalEcGetDetailsService

 payPalEcDoPaymentService

 payPalDoCaptureService

Example 4 Request for payPalEcSetService

payPalEcSetService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

purchaseTotals_currency=USD

payPalEcSetService_paypalReturn=http://www.cybersource.com

payPalEcSetService_paypalCancelReturn=http://www.cybersource.com/cancel

payPalEcSetService_paypalBillingAgreementDesc=

Home Town Newspaper Online*4.99 per month

payPalEcSetService_paypalBillingAgreementCustom=One-year subscription

payPalEcSetService_paypalBillingType=MerchantInitiatedBilling

payPalEcSetService_paypalPaymentType=instant

purchaseTotals_grandTotalAmount=4.99

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 5 Reply from payPalEcSetService

decision=ACCEPT

reasonCode=100

payPalEcSetReply_reasonCode=100

requestID=1928320121920167904854

requestToken=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchantReferenceCode=HTNsubscription9647

payPalEcSetReply_correlationID=4lks03uw2lbwxu

payPalEcSetReply_paypalToken=EC-2UN29359TV924162S

payPalEcSetReply_errorCode=93045SLWVO

payPalEcSetReply_amount=4.99

Example 6 Request for payPalEcGetDetailsService

payPalEcGetDetailsService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalEcGetDetailsService_paypalEcSetRequestID=1928320121920167904854

payPalEcGetDetailsService_paypalEcSetRequestToken=

Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

payPalEcGetDetailsService_paypalToken=EC-2UN29359TV924162S

Example 7 Reply from payPalEcGetDetailsService

decision=ACCEPT

reasonCode=100

payPalEcGetDetailsReply_reasonCode=100

requestID=29FJBLS93TBQPSLDGK3H

requestToken=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchantReferenceCode=HTNsubscription9647

payPalEcGetDetailsReply_paypalBillingAgreementAcceptedStatus=1

payPalEcGetDetailsReply_correlationID=sldkf9325sdfsdlkjgj

payPalEcGetDetailsReply_avsCode=3

payPalEcGetDetailsReply_paypalToken=EC-2UN29359TV924162S

payPalEcGetDetailsReply_errorCode=93045SLWVO

payPalEcGetDetailsReply_addressStatus=Confirmed

payPalEcGetDetailsReply_payerID=S6D5ETGSVYX94

payPalEcGetDetailsReply_payerStatus=verified

payPalEcGetDetailsReply_payerFirstname=Jane

payPalEcGetDetailsReply_payerLastname=Smith

payPalEcGetDetailsReply_payerCountry=US

payPalEcGetDetailsReply_payer=jsm[email protected]

payPalEcGetDetailsReply_shipToName=Jane Smith

payPalEcGetDetailsReply_shipToAddress1=1295 Charleston Rd.

payPalEcGetDetailsReply_shipToCity=Mountain View

payPalEcGetDetailsReply_shipToState=CA

payPalEcGetDetailsReply_shipToCountry=US

payPalEcGetDetailsReply_shipToZip=94043

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 8 Request for payPalEcDoPaymentService

payPalEcDoPaymentService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalEcDoPaymentService_paypalEcSetRequestID=1928323124420167904854

payPalEcDoPaymentService_paypalEcSetRequestToken=

Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

payPalEcDoPaymentService_paypalToken=EC-2UN29359TV924162S

payPalEcDoPaymentService_paypalCu[email protected]

payPalEcDoPaymentService_paypalPayerId=S6D5ETGSVYX94

purchaseTotals_currency=USD

purchaseTotals_grandTotalAmount=4.99

Example 9 Reply from payPalEcDoPaymentService

decision=ACCEPT

reasonCode=100

payPalEcDoPaymentReply_reasonCode=100

requestID=TN10C8B3MHS0AK3BKSGN8

requestToken=Crdug4OkpF2Qfd8oXDD0ZE4vpp24

merchantReferenceCode=HTNsubscription9647

payPalEcDoPaymentReply_paypalBillingAgreementId=3ADOib340UWM8923lf20

payPalEcDoPaymentReply_correlationID=sldkf9325sdfsdlkjgj

payPalEcDoPaymentReply_paypalToken=EC-2UN29359TV924162S

payPalEcDoPaymentReply_paypalPaymentStatus=Pending

payPalEcDoPaymentReply_transactionId=2YG99268YE540943P

payPalEcDoPaymentReply_paymentType=None

payPalEcDoPaymentReply_paypalTaxAmount=0.00

payPalEcDoPaymentReply_orderId=O-58X525738C493004E

payPalEcDoPaymentReply_paypalTransactiontype=expresscheckout

payPalEcDoPaymentReply_paypalPendingReason=order

payPalEcDoPaymentReply_errorCode=93045SLWVO

Example 10 Request for payPalDoCaptureService

payPalDoCaptureService_run=true

merchantID=HomeTownNewspaper

merchantReferenceNumber=HTNsubscription9647

payPalDoCaptureService_paypalEcDoPaymentRequestID=TN10C8B3MHS0AK3BKSGN8

payPalDoCaptureService_paypalEcDoPaymentRequestToken=

Crdug4OkpF2Qfd8oXDD0ZE4vpp24

payPalDoCaptureService_completeType=Complete

payPalDoCaptureService_paypalAuthorizationId=2YG99268YE540943P

purchaseTotals_grandTotalAmount=4.99

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Billing Agreement without Payment

This example shows how to create a billing agreement without payment by calling these

services:

 payPalEcSetService

 payPalEcGetDetailsService

 payPalCreateAgreementService

Example 11 Reply from payPalDoCaptureService

decision=ACCEPT

reasonCode=100

payPalDoCaptureReply_reasonCode=100

requestID=FY25W8N9OWC2LE7WOCBU5

requestToken=Dtely5OsoW3Pnw0mWVV9x26mll35

merchantReferenceCode=HTNsubscription9647

payPalDoCaptureReply_transactionId=2SA82969X3543562X

payPalDoCaptureReply_parentTransactionId=2YG99268YE540943P

payPalDoCaptureReply_authorizationId=2YG99268YE540943P

payPalDoCaptureReply_paypalPaymentStatus=Completed

payPalDoCaptureReply_errorCode=93045SLWVO

payPalDoCaptureReply_correlationId=gwlbof9325biwflpaj

payPalDoCaptureReply_paypalPaymentType=instant

payPalDoCaptureReply_paypalPaymentGrossAmount=4.99

payPalDoCaptureReply_paypalTaxAmount=0.00

payPalDoCaptureReply_paypalFeeAmount=0.36

payPalDoCaptureReply_paypalTransactiontype=expresscheckout

Example 12 Request for payPalEcSetService

payPalEcSetService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

purchaseTotals_currency=USD

payPalEcSetService_paypalReturn=http://www.cybersource.com

payPalEcSetService_paypalCancelReturn=http://www.cybersource.com/cancel

payPalEcSetService_paypalBillingAgreementDesc=

Home Town Newspaper Online*4.99 per month

payPalEcSetService_paypalBillingAgreementCustom=One-year subscription

payPalEcSetService_paypalBillingType=MerchantInitiatedBilling

payPalEcSetService_paypalPaymentType=instant

purchaseTotals_grandTotalAmount=0

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 13 Reply from payPalEcSetService

decision=ACCEPT

reasonCode=100

payPalEcSetReply_reasonCode=100

requestID=1928320121920167904854

requestToken=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchantReferenceCode=HTNsubscription9647

payPalEcSetReply_correlationID=4lks03uw2lbwxu

payPalEcSetReply_paypalToken=EC-2UN29359TV924162S

payPalEcSetReply_errorCode=93045SLWVO

payPalEcSetReply_amount=0

Example 14 Request for payPalEcGetDetailsService

payPalEcGetDetailsService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalEcGetDetailsService_paypalEcSetRequestID=1928320121920167904854

payPalEcGetDetailsService_paypalEcSetRequestToken=

Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

payPalEcGetDetailsService_paypalToken=EC-2UN29359TV924162S

Example 15 Reply from payPalEcGetDetailsService

decision=ACCEPT

reasonCode=100

payPalEcGetDetailsReply_reasonCode=100

requestID=29FJBLS93TBQPSLDGK3H

requestToken=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchantReferenceCode=HTNsubscription9647

payPalEcGetDetailsReply_paypalBillingAgreementAcceptedStatus=1

payPalEcGetDetailsReply_correlationID=sldkf9325sdfsdlkjgj

payPalEcGetDetailsReply_avsCode=3

payPalEcGetDetailsReply_paypalToken=EC-2UN29359TV924162S

payPalEcGetDetailsReply_errorCode=93045SLWVO

payPalEcGetDetailsReply_addressStatus=Confirmed

payPalEcGetDetailsReply_payerID=S6D5ETGSVYX94

payPalEcGetDetailsReply_payerStatus=verified

payPalEcGetDetailsReply_payerFirstname=Jane

payPalEcGetDetailsReply_payerLastname=Smith

payPalEcGetDetailsReply_payerCountry=US

payPalEcGetDetailsReply_payer=jsm[email protected]

payPalEcGetDetailsReply_shipToName=Jane Smith

payPalEcGetDetailsReply_shipToAddress1=1295 Charleston Rd.

payPalEcGetDetailsReply_shipToCity=Mountain View

payPalEcGetDetailsReply_shipToState=CA

payPalEcGetDetailsReply_shipToCountry=US

payPalEcGetDetailsReply_shipToZip=94043

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Reference Transaction

This example shows how to use a reference transaction to authorize and capture a

payment by calling these services:

 payPalDoRefTransactionService

 payPalAuthorizationService

 payPalDoCaptureService

Example 16 Request for payPalCreateAgreementService

payPalCreateAgreementService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalCreateAgreementService_

paypalEcSetRequestID=1928320121920167904854

payPalCreateAgreementService_paypalEcSetRequestToken=

Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

payPalCreateAgreementService_paypalToken=EC-2UN29359TV924162S

Example 17 Reply from payPalCreateAgreementService

decision=ACCEPT

reasonCode=100

payPalCreateAgreementReply_reasonCode=100

requestID=29FJBLS93TBQPSLDGK3H

requestToken=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchantReferenceCode=HTNsubscription9647

payPalCreateAgreementReply_

paypalBillingAgreementId=3ADOib340UWM8923lf20

Example 18 Request for payPalDoRefTransactionService

payPalDoRefTransactionService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

purchaseTotals_currency=USD

purchaseTotals_grandTotalAmount=4.99

payPalDoRefTransactionService_

paypalBillingAgreementId=3ADOib340UWM8923lf20

payPalDoRefTransactionService_paypalPaymentType=instant

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 19 Reply from payPalDoRefTransactionService

decision=ACCEPT

reasonCode=100

requestID=023mbdgil2spfkgjqdbvn

requestToken=slbiw9345BJldbodflBNQCPE1409D9k

merchantReferenceCode=HTNsubscription9647

payPalDoRefTransactionReply_reasonCode=100

payPalDoRefTransactionReply_correlationID=4lks03uw2lbwxu

payPalDoRefTransactionReply_paypalToken=EC-2UN29359TV924162S

payPalDoRefTransactionReply_errorCode=93045SLWVO

payPalDoRefTransactionReply_amount=4.99

payPalDoRefTransactionReply_currency=USD

payPalDoRefTransactionReply_paypalAmount=4.99

payPalDoRefTransactionReply_

paypalBillingAgreementId=3ADOib340UWM8923lf20

payPalDoRefTransactionReply_paypalOrderTime=2009-08-15T17:23:09Z

payPalDoRefTransactionReply_paypalPaymentStatus=Completed

payPalDoRefTransactionReply_paypalPaymentType=instant

payPalDoRefTransactionReply_paypalPendingReason=none

payPalDoRefTransactionReply_paypalReasonCode=none

payPalDoRefTransactionReply_paypalTaxAmount=0.00

payPalDoRefTransactionReply_paypalTransactiontype=express-checkout

payPalDoRefTransactionReply_transactionId=htnsubw30bwlbnq2

Example 20 Request for payPalAuthorizationService

payPalAuthorizationService_run=true

payPalAuthorizationService_paypalOrderId=58X525738C493004E

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

purchaseTotals_currency=USD

purchaseTotals_grandTotalAmount=4.99

payPalAuthorizationService_paypalDoRefTransactionRequestID=

023mbdgil2spfkgjqdbv

payPalAuthorizationService_paypalDoRefTransactionRequestToken=

slbiw9345BJldbodflBNQCPE1409D9k

payPalAuthorizationService_paypal[email protected]

[email protected]

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 21 Reply from payPalAuthorizationService

decision=ACCEPT

reasonCode=100

requestID=49gks2og0g12wrg879aergsk

requestToken=SLGQ30B235b0XCV0lskb2369awopSgm

merchantReferenceCode=HTNsubscription9647

payPalAuthorizationReply_reasonCode=100

payPalAuthorizationReply_correlationID=4lks03uw2lbwxu

payPalAuthorizationReply_errorCode=93045SLWVO

payPalAuthorizationReply_amount=4.99

payPalAuthorizationReply_currency=USD

payPalAuthorizationReply_paypalAmount=4.99

payPalAuthorizationReply_transactionId=3GT12375C398240X

payPalAuthorizationReply_orderId=58X525738C493004E

Example 22 Request for payPalDoCaptureService

payPalDoCaptureService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

purchaseTotals_currency=USD

purchaseTotals_grandTotalAmount=4.99

payPalDoCaptureService_completeType=Complete

payPalDoCaptureService_paypalAuthorizationRequestID=

49gks2og0g12wrg879aergsk

payPalDoCaptureService_paypalAuthorizationRequestToken=

SLGQ30B235b0XCV0lskb2369awopSgm

payPalDoCaptureService_paypalAuthorizationId=9XT12375C2469923X

Example 23 Reply from payPalDoCaptureService

decision=ACCEPT

reasonCode=100

requestID=203948106391278015965

requestToken=FFv9VEdZAOGh084W7RJzIIzHUTUL

merchantReferenceCode=HTNsubscription9647

payPalDoCaptureReply_reasonCode=100

payPalDoCaptureReply_paypalPaymentType=instant

payPalDoCaptureReply_paypalPaymentGrossAmount=4.99

payPalDoCaptureReply_paypalTaxAmount=0.00

payPalDoCaptureReply_currency=USD

payPalDoCaptureReply_paypalFeeAmount=0.36

payPalDoCaptureReply_amount=4.99

payPalDoCaptureReply_paypalTransactiontype=cart

payPalDoCaptureReply_transactionId=4M8612956X2810426

payPalDoCaptureReply_parentTransactionId=9XT12375C2469923X

payPalDoCaptureReply_authorizationId=0YU23486D3570034Y

payPalDoCaptureReply_paypalPaymentStatus=Completed

payPalDoCaptureReply_correlationId=r2lvp9325sdfsdlkjgj

payPalDoCaptureReply_errorCode=sboe93045

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Cancellation

This example shows how to cancel a billing agreement by calling the

payPalUpdateAgreementService service.

Example 24 Request for payPalUpdateAgreementService

payPalUpdateAgreementService_run=true

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalUpdateAgreementService_

paypalBillingAgreementID=3ADOib340UWM8923lf20

payPalUpdateAgreementService_paypalBillingAgreementStatus=Canceled

Example 25 Reply from payPalUpdateAgreementService

decision=ACCEPT

reasonCode=100

payPalUpdateAgreementReply_reasonCode=100

requestID=LRMB83bzwl39b8qen

requestToken=Ydlt020bjUPZ4bwpc6937prh

merchantReferenceCode=HTNsubscription9647

payPalUpdateAgreementReply_addressStatus=Confirmed

payPalUpdateAgreementReply_payer=[email protected]

payPalUpdateAgreementReply_payerBusiness=Home Town Newspaper

payPalUpdateAgreementReply_payerCountry=US

payPalUpdateAgreementReply_payerFirstname=Jane

payPalUpdateAgreementReply_payerLastname=Smith

payPalUpdateAgreementReply_payerId=S6D5ETGSVYX94

payPalUpdateAgreementReply_payerStatus=verified

payPalUpdateAgreementReply_paypalBillingAgreementCustom=

One-year subscription

payPalUpdateAgreementReply_paypalBillingAgreementDesc=

Home Town Newspaper Online*4.99 per month

payPalUpdateAgreementReply_

paypalBillingAgreementID=3ADOib340UWM8923lf20

payPalUpdateAgreementReply_paypalBillingAgreementStatus=Canceled

payPalUpdateAgreementReply_correlationId=4lks03uw2lbwxu

payPalUpdateAgreementReply_errorCode=93045SLWVO

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Item-Level Examples

To enable item-level fields, contact Cybersource Customer Support to have

your account configured for this feature.

Example 26 Request for payPalEcSetService

payPalEcSetService_run=true

merchantID=HomeTownBooks

merchantReferenceCode=HTBorder9647

purchaseTotals_currency=USD

payPalEcSetService_paypalReturn=http://www.cybersource.com

payPalEcSetService_paypalCancelReturn=http://www.cybersource.com/cancel

item_0_productCode=books

item_0_productName=Merriam-Webster Dictionary

item_0_productSKU=23456

item_0_quantity=1

item_0_unitPrice=22.00

item_0_taxAmount=1.10

item_1_productCode=books

item_1_productName=Handbook of English Grammar

item_1_productSKU=23458

item_1_quantity=1

item_1_unitPrice=24.00

item_1_taxAmount=1.20

item_2_productCode=books

item_2_productName=Roget's Thesaurus

item_2_productSKU=23450

item_2_quantity=1

item_2_unitPrice=16.00

item_2_taxAmount=0.80

item_3_productCode=coupon

item_3_productName=First-Time Buyer Coupon

item_3_productSKU=97531

item_3_quantity=1

item_3_unitPrice=5.00

item_4_productCode=shipping_and_handling

item_4_unitPrice=7.95

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 27 Reply from payPalEcSetService

decision=ACCEPT

reasonCode=100

payPalEcSetReply_reasonCode=100

requestID=KPTRWUMC123893lsng

requestToken=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchantReferenceCode=HTBorder9647

payPalEcSetReply_paypalToken=349GJlk2jk34993

payPalEcSetReply_correlationID=5lks03uw3lawxz

payPalEcSetReply_errorCode=911245SVtsO

Example 28 Request for payPalEcGetDetailsService

payPalEcGetDetailsService_run=true

merchantID=HomeTownBooks

merchantReferenceCode=HTBorder9647

payPalEcGetDetailsService_payPalEcSetRequestID=KPTRWUMC123893lsng

payPalEcGetDetailsService_paypalEcSetRequestToken=

Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

payPalEcGetDetailsService_paypalToken=349GJlk2jk34993

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 29 Reply from payPalEcGetDetailsService

decision=ACCEPT

reasonCode=100

payPalEcGetDetailsReply_reasonCode=100

requestID=RZ34980sctj2

requestToken=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchantReferenceCode=HTBorder9647

payPalEcGetDetailsReply_paypalToken=349GJlk2jk34993

payPalEcGetDetailsReply_correlationID=6ksz03np4lbwxy

payPalEcGetDetailsReply_errorCode=822236PXnw3

payPalEcGetDetailsReply_avsCode=3

payPalEcGetDetailsReply_addressStatus=Confirmed

payPalEcGetDetailsReply_payerID=S6D5ETGSVYX94

payPalEcGetDetailsReply_payerStatus=verified

payPalEcGetDetailsReply_payerFirstname=Jane

payPalEcGetDetailsReply_payerLastname=Smith

payPalEcGetDetailsReply_payerCountry=US

payPalEcGetDetailsReply_payer=jsm[email protected]

payPalEcGetDetailsReply_shipToName=Jane Smith

payPalEcGetDetailsReply_shipToAddress1=1295 Charleston Rd.

payPalEcGetDetailsReply_shipToCity=Mountain View

payPalEcGetDetailsReply_shipToState=CA

payPalEcGetDetailsReply_shipToCountry=US

payPalEcGetDetailsReply_shipToZip=94043

payPalEcGetDetailsReply_paypalTaxAmount=3.10

item_0_productCode=default

item_0_productName=Merriam-Webster Dictionary

item_0_productSKU=23456

item_0_quantity=1

item_0_unitPrice=22.00

item_1_productCode=default

item_1_productName=Handbook of English Grammar

item_1_productSKU=23458

item_1_quantity=1

item_1_unitPrice=24.00

item_2_productCode=default

item_2_productName=Roget's Thesaurus

item_2_productSKU=23450

item_2_quantity=1

item_2_unitPrice=16.00

item_3_productCode=coupon

item_3_productName=First-Time Buyer Coupon

item_3_productSKU=97531

item_3_quantity=1

item_3_unitPrice=5.00

item_4_productCode=shipping_and_handling

item_4_unitPrice=7.95

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Transaction Search Example

Example 30 Request for payPalTransactionSearchService

merchantID=HomeTownNewspaper

merchantReferenceCode=HTNsubscription9647

payPalTransactionSearchService_run=true

payPalTransactionSearchService_startDate=2012-09-25T18:47:13Z

payPalTransactionSearchService_endDate=2012-09-25T18:49:13Z

payPalTransactionSearchService_pa[email protected]

payPalTransactionSearchService_transactionID=93N51798SX666845X

payPalTransactionSearchService_invoiceNumber=0001529

payPalTransactionSearchService_grandTotalAmount=5.00

payPalTransactionSearchService_currency=USD

payPalTransactionSearchService_paymentStatus=Success

payPalTransactionSearchService_payerFirstname=Jane

payPalTransactionSearchService_payerLastname=Smith

Example 31 Reply from payPalTransactionSearchService

merchantReferenceCode=HTNsubscription9647

requestID=3485988938400181552773

decision=ACCEPT

reasonCode=100

requestToken=AhjrLwSRefOhK9P3yQ0KIJp7HBMVhNPMrTnpa4sA/H2H

payPalTransactionSearchReply_reasonCode=100

payPalTransactionSearchReply_transaction_0_transactionTime=2012-09-25T18:48:11Z

payPalTransactionSearchReply_transaction_0_transactionTimeZone=GMT

payPalTransactionSearchReply_transaction_0_transactionType=Payment

payPalTransactionSearchReply_transaction_0_paypalPayerOrPayeeEmail=jsmith@example.com

payPalTransactionSearchReply_transaction_0_customerDisplayName=Jane Smith

payPalTransactionSearchReply_transaction_0_transactionID=93N51798SX666845X

payPalTransactionSearchReply_transaction_0_paypalPaymentStatus=Completed

payPalTransactionSearchReply_transaction_0_grandTotalAmount=5.00

payPalTransactionSearchReply_transaction_0_currency=USD

payPalTransactionSearchReply_transaction_0_paypalFeeAmount=-0.45

payPalTransactionSearchReply_transaction_0_paypalNetAmount=4.55

payPalTransactionSearchReply_transaction_1_transactionTime=2012-09-25T18:48:05Z

payPalTransactionSearchReply_transaction_1_transactionTimeZone=GMT

payPalTransactionSearchReply_transaction_1_transactionType=Authorization

payPalTransactionSearchReply_transaction_1_paypalPayerOrPayeeEmail=jsmith@example.com

payPalTransactionSearchReply_transaction_1_customerDisplayName=Jane Smith

payPalTransactionSearchReply_transaction_1_transactionID=8KV00008PR858651B

payPalTransactionSearchReply_transaction_1_paypalPaymentStatus=Completed

payPalTransactionSearchReply_transaction_1_grandTotalAmount=5.00

payPalTransactionSearchReply_transaction_1_currency=USD

payPalTransactionSearchReply_transaction_1_paypalFeeAmount=0.00

payPalTransactionSearchReply_transaction_1_paypalNetAmount=5.00

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

XML Examples

Billing Agreement Examples

Billing Agreement with Payment

This example shows how to create a billing agreement with payment by calling these

services:

 payPalEcSetService

 payPalEcGetDetailsService

 payPalEcDoPaymentService

 payPalDoCaptureService

Example 32 Request for payPalEcSetService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalReturn>http://www.cybersource.com</paypalReturn>

<paypalCancelReturn>http://www.cybersource.com/cancel</paypalCancelReturn>

<paypalBillingAgreementDesc>Home Town Newspaper Online*4.99 per month

</paypalBillingAgreementDesc>

<paypalBillingType>MerchantInitiatedBilling</paypalBillingType>

<paypalPaymentType>instant</paypalPaymentType>

<paypalBillingAgreementCustom>One-year subscription

</paypalBillingAgreementCustom>

</payPalEcSetService>

</purchaseTotals>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 33 Reply from payPalEcSetService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>1928320121920167904854</c:requestID>

<c:requestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalEcSetReply>

<c:reasonCode>100</c:reasonCode>

<c:correlationID>4lks03uw2lbwxu</c:correlationID>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:errorCode>93045SLWVO</c:errorCode>

<c:amount>4.99</c:amount>

</c:payPalEcSetReply>

</c:replyMessage>

Example 34 Request for payPalEcGetDetailsService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalEcSetRequestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

</paypalEcSetRequestToken>

</payPalEcGetDetailsService>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 35 Reply from payPalEcGetDetailsService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>29FJBLS93TBQPSLDGK3H</c:requestID>

<c:requestToken>Bxwje3Ijb7OskjK6HGG0XF3vllnoyf</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalEcGetDetailsReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalBillingAgreementAcceptedStatus>1

</c:paypalBillingAgreementAcceptedStatus>

<c:correlationID>sldkf9325sdfsdlkjgj</c:correlationID>

<c:avsCode>3</c:avsCode>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:errorCode>93045SLWVO</c:errorCode>

<c:addressStatus>Confirmed</c:addressStatus>

<c:payerID>S6D5ETGSVYX94</c:payerID>

<c:payerStatus>verified</c:payerStatus>

<c:payerFirstname>Jane</c:payerFirstname>

<c:payerLastname>Smith</c:payerLastname>

<c:payerCountry>US</c:payerCountry>

<c:payer>[email protected]</c:payer>

<c:shipToName>Jane Smith</c:shipToName>

<c:shipToAddress1>1295 Charleston Rd.</c:shipToAddress1>

<c:shipToCity>Mountain View</c:shipToCity>

<c:shipToState>CA</c:shipToState>

<c:shipToCountry>US</c:shipToCountry>

<c:shipToZip>94043</c:shipToZip>

</c:payPalEcGetDetailsReply>

</c:replyMessage>

Example 36 Request for payPalEcDoPaymentService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalPayerId>S6D5ETGSVYX94</paypalPayerId>

<paypalCustomerEmail>jsmith@examples.com</paypalCustomerEmail>

<paypalEcSetRequestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

</paypalEcSetRequestToken>

</payPalEcDoPaymentService>

</purchaseTotals>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 37 Reply from payPalEcDoPaymentService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>TN10C8B3MHS0AK3BKSGN8</c:requestID>

<c:requestToken>Crdug4OkpF2Qfd8oXDD0ZE4vpp24</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalEcDoPaymentReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalBillingAgreementId>3ADOib340UWM8923lf20

</c:paypalBillingAgreementId>

<c:correlationID>sldkf9325sdfsdlkjgj</c:correlationID>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:paypalPaymentStatus>Pending</c:paypalPaymentStatus>

<c:transactionId>2YG99268YE540943P</c:transactionId>

<c:paymentType>None</c:paymentType>

<c:paypalTaxAmount>0.00</c:paypalTaxAmount>

<c:orderId>O-58X525738C493004E</c:orderId>

<c:paypalTransactiontype>expresscheckout</c:paypalTransactiontype>

<c:paypalPendingReason>order</c:paypalPendingReason>

<c:errorCode>93045SLWVO</c:errorCode>

</c:payPalEcDoPaymentReply>

</c:replyMessage>

Example 38 Request for payPalDoCaptureService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<completeType>Complete</completeType>

<paypalEcDoPaymentRequestID>TN10C8B3MHS0AK3BKSGN8

</paypalEcDoPaymentRequestID>

<paypalEcDoPaymentRequestToken>Crdug4OkpF2Qfd8oXDD0ZE4vpp24

</paypalEcDoPaymentRequestToken>

</payPalDoCaptureService>

</purchaseTotals>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 39 Reply from payPalDoCaptureService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>FY25W8N9OWC2LE7WOCBU5</c:requestID>

<c:requestToken>Dtely5OsoW3Pnw0mWVV9x26mll35</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalDoCaptureReply>

<c:reasonCode>100</c:reasonCode>

<c:transactionId>2SA82969X3543562X</c:transactionId>

<c:parentTransactionId>2YG99268YE540943P</c:parentTransactionId>

<c:authorizationId>2YG99268YE540943P</c:authorizationId>

<c:paypalPaymentStatus>Completed</c:paypalPaymentStatus>

<c:errorCode>93045SLWVO</c:errorCode>

<c:correlationId>gwlbof9325biwflpaj</c:correlationId>

<c:paypalPaymentType>instant</c:paypalPaymentType>

<c:paypalPaymentGrossAmount>4.99</c:paypalPaymentGrossAmount>

<c:paypalTaxAmount>0.00</c:paypalTaxAmount>

<c:paypalFeeAmount>0.36</c:paypalFeeAmount>

<c:paypalTransactiontype>expresscheckout</c:paypalTransactiontype>

</c:payPalDoCaptureReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Billing Agreement without Payment

This example shows how to create a billing agreement without payment by calling these

services:

 payPalEcSetService

 payPalEcGetDetailsService

 payPalCreateAgreementService

Example 40 Request for payPalEcSetService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalReturn>http://www.cybersource.com</paypalReturn>

<paypalCancelReturn>http://www.cybersource.com/cancel</paypalCancelReturn>

<paypalBillingType>MerchantInitiatedBilling</paypalBillingType>

<paypalBillingAgreementDesc>Home Town Newspaper Online*4.99 per month

</paypalBillingAgreementDesc>

<paypalPaymentType>instant</paypalPaymentType>

<paypalBillingAgreementCustom>One-year subscription

</paypalBillingAgreementCustom>

</payPalEcSetService>

</purchaseTotals>

</requestMessage>

Example 41 Reply from payPalEcSetService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>1928320121920167904854</c:requestID>

<c:requestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalEcSetReply>

<c:reasonCode>100</c:reasonCode>

<c:correlationID>4lks03uw2lbwxu</c:correlationID>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:errorCode>93045SLWVO</c:errorCode>

<c:amount>0</c:amount>

</c:payPalEcSetReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

Example 42 Request for payPalEcGetDetailsService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalEcSetRequestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

</paypalEcSetRequestToken>

</payPalEcGetDetailsService>

</requestMessage>

Example 43 Reply from payPalEcGetDetailsService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>29FJBLS93TBQPSLDGK3H</c:requestID>

<c:requestToken>Bxwje3Ijb7OskjK6HGG0XF3vllnoyf</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalEcGetDetailsReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalBillingAgreementAcceptedStatus>1

</c:paypalBillingAgreementAcceptedStatus>

<c:correlationID>sldkf9325sdfsdlkjgj</c:correlationID>

<c:avsCode>3</c:avsCode>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:errorCode>93045SLWVO</c:errorCode>

<c:addressStatus>Confirmed</c:addressStatus>

<c:payerID>S6D5ETGSVYX94</c:payerID>

<c:payerStatus>verified</c:payerStatus>

<c:payerFirstname>Jane</c:payerFirstname>

<c:payerLastname>Smith</c:payerLastname>

<c:payerCountry>US</c:payerCountry>

<c:payer>[email protected]</c:payer>

<c:shipToName>Jane Smith</c:shipToName>

<c:shipToAddress1>1295 Charleston Rd.</c:shipToAddress1>

<c:shipToCity>Mountain View</c:shipToCity>

<c:shipToState>CA</c:shipToState>

<c:shipToCountry>US</c:shipToCountry>

<c:shipToZip>94043</c:shipToZip>

</c:payPalEcGetDetailsReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

100

Example 44 Request for payPalCreateAgreementService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalEcSetRequestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

</paypalEcSetRequestToken>

</payPalCreateAgreementService>

</requestMessage>

Example 45 Reply from payPalCreateAgreementService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<crequestID>29FJBLS93TBQPSLDGK3H</c:requestID>

<c:requestToken>Bxwje3Ijb7OskjK6HGG0XF3vllnoyf</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalCreateAgreementReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalBillingAgreementId>3ADOib340UWM8923lf20

</c:paypalBillingAgreementId>

</c:payPalCreateAgreementReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

101

Reference Transaction

This example shows how to use a reference transaction to authorize and capture a

payment by calling these services:

 payPalDoRefTransactionService

 payPalAuthorizationService

 payPalDoCaptureService

Example 46 Request for payPalDoRefTransactionService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalBillingAgreementId>3ADOib340UWM8923lf20</paypalBillingAgreementId>

<paypalPaymentType>instant</paypalPaymentType>

</payPalDoRefTransactionService>

</purchaseTotals>

</requestMessage>

Example 47 Reply from payPalDoRefTransactionService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>023mbdgil2spfkgjqdbvn</c:requestID>

<c:requestToken>slbiw9345BJldbodflBNQCPE1409D9k</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalDoRefTransactionReply>

<c:reasonCode>100</c:reasonCode>

<c:correlationID>4lks03uw2lbwxu</c:correlationID>

<c:paypalToken>EC-2UN29359TV924162S</c:paypalToken>

<c:errorCode>93045SLWVO</c:errorCode>

<c:amount>4.99</c:amount>

<c:currency>USD</c:currency>

<c:paypalAmount>4.99</c:paypalAmount>

<c:paypalBillingAgreementId>3ADOib340UWM8923lf20</c:paypalBillingAgreementId>

<c:paypalOrderTime>2009-08-15T17:23:09Z</c:paypalOrderTime>

<c:paypalPaymentStatus>Completed</c:paypalPaymentStatus>

<c:paypalPaymentType>instant</c:paypalPaymentType>

<c:paypalPendingReason>none</c:paypalPendingReason>

<c:paypalReasonCode>none</c:paypalReasonCode>

<c:paypalTaxAmount>0.00</c:paypalTaxAmount>

<c:paypalTransactiontype>express-checkout</c:paypalTransactiontype>

<c:transactionId>htnsubw30bwlbnq2</c:transactionId>

</c:payPalDoRefTransactionReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

102

Example 48 Request for payPalAuthorizationService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalDoRefTransactionRequestID>023mbdgil2spfkgjqdbvn

</paypalDoRefTransactionRequestID>

<paypalDoRefTransactionRequestToken>slbiw9345BJldbodflBNQCPE1409D9k

</paypalDoRefTransactionRequestToken>

<paypalCustomerEmail>jsmith@example.com</paypalCustomerEmail>

</payPalAuthorizationService>

</purchaseTotals>

</requestMessage>

Example 49 Reply from payPalAuthorizationService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>49gks2og0g12wrg879aergsk</c:requestID>

<c:requestToken>SLGQ30B235b0XCV0lskb2369awopSgm</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalAuthorizationReply>

<c:reasonCode>100</c:reasonCode>

<c:correlationID>4lks03uw2lbwxu</c:correlationID>

<c:errorCode>93045SLWVO</c:errorCode>

<c:amount>4.99</c:amount>

<c:currency>USD</c:currency>

<c:paypalAmount>4.99</c:paypalAmount>

<c:transactionId>3GT12375C398240X</c:transactionId>

</c:payPalAuthorizationReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

103

Example 50 Request for payPalDoCaptureService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<completeType>Complete</completeType>

<paypalAuthorizationRequestID>49gks2og0g12wrg879aergsk

</paypalAuthorizationRequestID>

<paypalAuthorizationRequestToken>SLGQ30B235b0XCV0lskb2369awopSgm

</paypalAuthorizationRequestToken>

</payPalDoCaptureService>

</purchaseTotals>

</requestMessage>

Example 51 Reply from payPalDoCaptureService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>203948106391278015965</c:requestID>

<c:requestToken>FFv9VEdZAOGh084W7RJzIIzHUTUL</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalDoCaptureReply>

<c:reasonCode>100</c:reasonCode>

<c:correlationID>r2lvp9325sdfsdlkjgj</c:correlationID>

<c:errorCode>sboe93045</c:errorCode>

<c:amount>4.99</c:amount>

<c:currency>USD</c:currency>

<c:paypalPaymentType>instant</c:paypalPaymentType>

<c:paypalPaymentGrossAmount>4.99</c:paypalPaymentGrossAmount>

<c:paypalTaxAmount>0.00</c:paypalTaxAmount>

<c:paypalFeeAmount>0.36</c:paypalFeeAmount>

<c:paypalTransactiontype>cart</c:paypalTransactiontype>

<c:transactionId>4M8612956X2810426</c:transactionId>

<c:parentTransactionId>9XT12375C2469923X</c:parentTransactionId>

<c:authorizationId>0YU23486D3570034Y</c:authorizationId>

<c:paypalPaymentStatus>Completed</c:paypalPaymentStatus>

</c:payPalDoCaptureReply>

<c:/replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

104

Cancellation

This example shows how to cancel a billing agreement by calling the

payPalUpdateAgreementService service.

Example 52 Request for payPalUpdateAgreementService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalBillingAgreementID>3ADOib340UWM8923lf20</paypalBillingAgreementID>

<paypalBillingAgreementStatus>Canceled</paypalBillingAgreementStatus>

</payPalUpdateAgreementService>

</requestMessage>

Example 53 Reply from payPalUpdateAgreementService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.47">

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestID>1928320121920167904854</c:requestID>

<c:requestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk</c:requestToken>

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:payPalUpdateAgreementReply>

<c:reasonCode>100</c:reasonCode>

<c:addressStatus>Confirmed</c:addressStatus>

<c:payer>[email protected]</c:payer>

<c:payerBusiness>Home Town Newspaper</c:payerBusiness>

<c:payerCountry>US</c:payerCountry>

<c:payerFirstname>Jane</c:payerFirstname>

<c:payerLastname>Smith</c:payerLastname>

<c:payerId>S6D5ETGSVYX94</c:payerId>

<c:payerStatus>verified</c:payerStatus>

<c:paypalBillingAgreementCustom>One-year subscription

</c:paypalBillingAgreementCustom>

<c:paypalBillingAgreementDesc>Home Town Newspaper Online*4.99 per month

</c:paypalBillingAgreementDesc>

<c:paypalBillingAgreementID>3ADOib340UWM8923lf20</c:paypalBillingAgreementID>

<c:paypalBillingAgreementStatus>Canceled</c:paypalBillingAgreementStatus>

<c:correlationID>4lks03uw2lbwxu</c:correlationID>

<c:errorCode>93045SLWVO</c:errorCode>

</c:payPalUpdateAgreementReply>

</c:replyMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

105

Item-Level Examples

To enable item-level fields, contact Cybersource Customer Support to have

your account configured for this feature.

Example 54 Request for payPalEcSetService

<merchantID>HomeTownBooks</merchantID>

<merchantReferenceCode>HTBorder9647</merchantReferenceCode>

<productCode>books</productCode>

<productName>Merriam-Webster Dictionary</productName>

</item>

<productCode>books</productCode>

<productName>Handbook of English Grammar</productName>

</item>

<productCode>books</productCode>

<productName>Roget's Thesaurus</productName>

</item>

<productCode>coupon</productCode>

<productName>First-Time Buyer Coupon</productName>

</item>

<productCode>shipping_and_handling</productCode>

</item>

<paypalReturn>http://www.cybersource.com</paypalReturn>

<paypalCancelReturn>http://www.cybersource.com/cancel</paypalCancelReturn>

</payPalEcSetService>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

106

Example 55 Reply from payPalEcSetService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.72">

<c:merchantReferenceCode>HTBorder9647</c:merchantReferenceCode>

<c:requestID>KPTRWUMC123893lsng</c:requestID>

<c:requestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk</c:requestToken>

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:payPalEcSetReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalToken>349GJlk2jk34993</c:paypalToken>

<c:correlationID>5lks03uw3lawxz</c:correlationID>

<c:errorCode>911245SVtsO</c:errorCode>

</c:payPalEcSetReply>

</c:replyMessage>

Example 56 Request for payPalEcGetDetailsService

<merchantID>HomeTownBooks</merchantID>

<merchantReferenceCode>HTBorder9647</merchantReferenceCode>

<payPalEcSetRequestID>KPTRWUMC123893lsng</payPalEcSetRequestID>

<paypalEcSetRequestToken>Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

</paypalEcSetRequestToken>

</payPalEcGetDetailsService>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

107

Example 57 Reply from payPalEcGetDetailsService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.78">

<c:merchantReferenceCode>HTBorder9647</c:merchantReferenceCode>

<c:requestID>RZ34980sctj2</c:requestID>

<c:requestToken>Bxwje3Ijb7OskjK6HGG0XF3vllnoyf</c:requestToken>

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<productCode>default</productCode>

<productName>Merriam-Webster Dictionary</productName>

</item>

<productCode>default</productCode>

<productName>Handbook of English Grammar</productName>

</item>

<productCode>default</productCode>

<productName>Roget's Thesaurus</productName>

</item>

<productCode>coupon</productCode>

<productName>First-Time Buyer Coupon</productName>

</item>

<productCode>shipping_and_handling</productCode>

</item>

<c:payPalEcGetDetailsReply>

<c:reasonCode>100</c:reasonCode>

<c:paypalToken>349GJlk2jk34993</c:paypalToken>

<c:payer>[email protected]</c:payer>

<c:payerID>S6D5ETGSVYX94</c:payerID>

<c:payerStatus>verified</c:payerStatus>

<c:payerFirstname>Jane</c:payerFirstname>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

108

Transaction Search Example

<c:payerLastname>Smith</c:payerLastname>

<c:payerCountry>US</c:payerCountry>

<c:shipToName>Jane Smith</c:shipToName>

<c:shipToAddress1>1295 Charleston Rd.</c:shipToAddress1>

<c:shipToCity>Mountain View</c:shipToCity>

<c:shipToState>CA</c:shipToState>

<c:shipToCountry>US</c:shipToCountry>

<c:shipToZip>94043</c:shipToZip>

<c:addressStatus>Confirmed</c:addressStatus>

<c:avsCode>3</c:avsCode>

<c:correlationID>6ksz03np4lbwxy</c:correlationID>

<c:errorCode>822236PXnw3</c:errorCode>

<c:paypalTaxAmount>3.10</c:paypalTaxAmount>

</c:payPalEcSetReply>

</c:replyMessage>

Example 57 Reply from payPalEcGetDetailsService (Continued)

Example 58 Request for payPalTransactionSearchService

<merchantID>HomeTownNewspaper</merchantID>

<merchantReferenceCode>HTNsubscription9647</merchantReferenceCode>

<paypalCustomerEmail>jsmith@example.com</paypalCustomerEmail>

<paymentStatus>Success</paymentStatus>

<payerLastname>Smith</payerLastname>

</payPalTransactionSearchService>

</requestMessage>

Chapter Examples

PayPal Express Checkout Services Using the Simple Order API |

109

Example 59 Reply from payPalTransactionSearchService

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.78">

<c:merchantReferenceCode>HTNsubscription9647</c:merchantReferenceCode>

<c:requestID>3485988938400181552773</c:requestID>

<c:decision>ACCEPT</c:decision>

<c:reasonCode>100</c:reasonCode>

<c:requestToken>AhjrLwSRefOhK9P3yQ0KIJp7HBMVhNPMrTnpa4sA/H2H</c:requestToken>

<c:payPalTransactionSearchReply>

<c:reasonCode>100</c:reasonCode>

<c:transaction id="0">

<c:transactionTime>2012-09-25T18:48:11Z</c:transactionTime>

<c:transactionTimeZone>GMT</c:transactionTimeZone>

<c:transactionType>Payment</c:transactionType>

<c:paypalPayerOrPayeeEmail>jsmith@example.com</c:paypalPayerOrPayeeEmail>

<c:customerDisplayName>Jane Smith</c:customerDisplayName>

<c:transactionID>93N51798SX666845X</c:transactionID>

<c:paypalPaymentStatus>Completed</c:paypalPaymentStatus>

<c:grandTotalAmount>5.00</c:grandTotalAmount>

<c:currency>USD</c:currency>

<c:paypalFeeAmount>-0.45</c:paypalFeeAmount>

<c:paypalNetAmount>4.55</c:paypalNetAmount>

</c:transaction>

<c:transaction id="1">

<c:transactionTime>2012-09-25T18:48:05Z</c:transactionTime>

<c:transactionTimeZone>GMT</c:transactionTimeZone>

<c:transactionType>Authorization</c:transactionType>

<c:paypalPayerOrPayeeEmail>jsmith@example.com</c:paypalPayerOrPayeeEmail>

<c:customerDisplayName>Jane Smith</c:customerDisplayName>

<c:transactionID>8KV00008PR858651B</c:transactionID>

<c:paypalPaymentStatus>Completed</c:paypalPaymentStatus>

<c:grandTotalAmount>5.00</c:grandTotalAmount>

<c:currency>USD</c:currency>

<c:paypalFeeAmount>0.00</c:paypalFeeAmount>

<c:paypalNetAmount>5.00</c:paypalNetAmount>

</c:transaction>

</c:payPalTransactionSearchReply>

</c:replyMessage>

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 110

Currency Codes

The following currency codes are supported for PayPal Express Checkout.

PayPal can add currencies at any time. For an up-to-date list of currencies

supported by PayPal, contact your PayPal representative.

To request transactions in currencies other than CNY for customers located in

China, contact Cybersource Customer Support to have your account

configured for this functionality.

Table 21 Currency Codes

Currency Code Currency

AUD Australian dollar

CAD Canadian dollar

CHF Swiss franc

CNY Chinese yuan renminbi

CZK Czech koruna

DKK Danish krone

EUR Euro

GBP British pound sterling

HKD Hong Kong dollar

HUF Hungarian forint

JPY Japanese yen

NOK Norwegian krone

NZD New Zealand dollar

PLN Polish zloty

SEK Swedish krona

SGD Singapore dollar

USD (default) United States dollar

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 111

Product Codes

The following table lists the values you can use for the product code in the item_#_

productCode request field.

Table 22 Product Codes

Product Code Definition

coupon

Coupon applied to the entire order.

default

Use this value when none of the other values apply.

handling_only

Fee that you charge your customer to cover your

administrative selling costs.

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.

CHAPTER

PayPal Express Checkout Services Using the Simple Order API | 112

Reason Codes

The following table lists the PayPal Express Checkout reason codes returned by the

Simple Order API. See the information about handling replies in Getting Started with

CyberSource Advanced for the Simple Order API for a discussion of replies and reason

codes.

Because Cybersource can add reply fields and reason codes at any time, do

the following:

 Parse the reply data according to the names of the fields instead of their

order in the reply. For more information about parsing reply fields, see the

documentation for your client.

 Program your error handler to use the decision field to determine the

result if it receives a reason code that it does not recognize.

Table 23 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 for

the Simple Order API.

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 for the

Simple Order API.

150 General system failure.

See the documentation for your Cybersource client for information about how to

handle retries in the case of system errors.

Chapter Reason Codes

PayPal Express Checkout Services Using the Simple Order API |

113

151 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.

223 PayPal rejected the transaction.

233 General decline by PayPal.

Possible action: request that the customer select a different form of payment at the

PayPal

web site.

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.

238 PayPal rejected the transaction. A successful transaction was already completed

for this paypalToken value.

387 Your call to payPalEcDoPaymentService failed. Cybersource successfully set up

the order with PayPal, but the authorization functionality failed.

Table 23 Reason Codes (Continued)

Reason

Code

Description

PayPal Express Checkout Services Using the Simple Order API | February 2021 114

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

agreements. See billing agreements

authorization IDs, defined 10

Authorization Reversal Service 35

authorization reversals

defined 19

requesting 35

Authorization Service 31

authorizations

delayed 16

requesting 31

reversing 35

billing agreement IDs, defined 10

billing agreements

canceling 37

creating 34

defined 18

updating 37

billing information, requesting 28

Buyer Complaint Process 21

cancellation

requesting 37

Cancellation Service 37

cancellations

defined 19

capture IDs, defined 10

Capture Service 32

captures

delayed 16

requesting 32

characters, special 41

chargebacks 21

check reference numbers 22

checkout methods, defined 9

consumer dispute rights 21

Create Agreement Service 34

credits, requesting 36

currency codes 110

custom orders, defined 16

customer information, requesting 28

data types 41

delayed authorizations, defined 16

delayed captures, defined 16

dispute rights 21

examples 80

Get Details Service 28

Get Transaction Details Service 38

honor periods, defined 10

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

Index

PayPal Express Checkout Services Using the Simple Order API |

115

immediate partial sales, defined 16

In-Context Express Checkout 13

naming conventions

reply fields 62

request fields 43

order IDs, defined 10

Order Setup Service 30

order setup, requesting 30

order tracking 22

payment method, defined 9

Payment Service 29

payments, requesting 29

PayPal accounts, setting up 11

prerequisites 11

processor transaction identifiers 22

product codes 111

promo codes 58

protection policy 21

reason codes 112

Reauthorization Service 36

reauthorizations

defined 19

procedure 36

reconciliation IDs 22

redirection URLs 25

Reference Transaction Service 34

reference transactions

defined 18

requesting 34

Refund Service 36

refunds

defined 19

requesting 36

regular orders, defined 15

reply fields 62

reports 20

request fields 43

request IDs 22

requirements 11

reversals

defined 19

requesting 35

Sale Service 33

sales

defined 15

procedure 33

Seller Protection Policy 21

session tokens, defined 10

Set Service 25

setting up orders 30

shortcut method, defined 9

special characters 41

split shipments 32

standard orders, defined 15

Traditional Express Checkout 13

transaction reference numbers 22

Transaction Search Service 37

transactions

requesting details about 38

search reply fields 78

searching for 37

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

Index

PayPal Express Checkout Services Using the Simple Order API |

116

updating billing agreements 37

URLs for live transactions 25