PayPal_Express_SCMP

Title Page

PayPal Express Checkout Services

Using the SCMP 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

REVISIONS

PayPal Express Checkout Services Using the SCMP API | 3

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 SCMP API (PDF | HTML)

describes how to get started using the SCMP API.

 The Classic 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 SCMP 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 21.

 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 SCMP 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 SCMP 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 SCMP API |

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

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.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP API |

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.

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.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP API |

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

"Redirection URLs," page 24.

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.

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

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP 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 4 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 16.

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP 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 5 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 SCMP 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 8, "Service Call Examples for Custom Orders," on page 18 provides

examples of a Delayed Authorization and a Delayed Capture.

Table 6 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 SCMP 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 15, 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 7 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 SCMP 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 8 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 9 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 SCMP 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 10 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 35 and "Get Transaction Details Service," page 37.

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 Classic 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 9 Additional PayPal Express Checkout Services (Continued)

Service or Function Description

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP 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 11 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 10 Methods of Obtaining Information About Your Transactions (Continued)

Method Description

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP API |

Order Tracking

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

Advanced for the SCMP 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 request_id.

Request IDs in Request Messages

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

request messages.

Table 12 Request IDs in Request Messages

Service Field Names

Set paypal_ec_set_request_id

Get Details paypal_ec_set_request_id

Do Payment paypal_ec_set_request_id

Do Capture For a standard order: paypal_ec_do_payment_request_id

For a custom order: paypal_authorization_request_id

Order Setup paypal_ec_set_request_id

Authorization For a custom order: paypal_ec_order_setup_request_id

For a billing agreement: paypal_do_ref_transaction_request_id

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP API |

Create

Agreement

paypal_ec_set_request_id

Authorization

Reversal

For a standard order: paypal_ec_do_payment_request_id

For a custom order when reversing an order setup:

paypal_ec_order_setup_request_id

For a custom order when reversing an authorization:

paypal_authorization_request_id

Refund paypal_do_capture_request_id

Table 12 Request IDs in Request Messages (Continued)

Service Field Names

Chapter 1 Introduction to PayPal Express Checkout

PayPal Express Checkout Services Using the SCMP API |

CHAPTER

PayPal Express Checkout Services Using the SCMP API | 23

Requesting Services

The SCMP API is Cybersource’s older, legacy API. If you are just beginning an

implementation with Cybersource, you should use the Simple Order API

instead of the SCMP API.

Table 13 Request Services

Group For a Delayed Authorization For a Delayed Capture

Standard Orders Set Service ics_paypal_ec_set

Get Details Service ics_paypal_ec_get_details

Payment Service ics_paypal_ec_do_payment

Capture Service ics_paypal_do_capture

Sale Service Multiple services

Custom Orders Set Service ics_paypal_ec_set

Get Details Service ics_paypal_ec_get_details

Order Setup Service ics_paypal_ec_order_setup

Authorization Service ics_paypal_authorization

Capture Service ics_paypal_do_capture

Billing Agreements Set Service ics_paypal_ec_set

Get Details Service ics_paypal_ec_get_details

Payment Service ics_paypal_ec_do_payment

Capture Service ics_paypal_do_capture

Create Agreement Service ics_paypal_create_agreement

Reference Transaction Service ics_paypal_do_ref_transaction

Authorization Service ics_paypal_authorization

Additional Services Authorization Reversal Service ics_paypal_auth_reversal

Refund Service ics_paypal_refund

Reauthorization Service Multiple services

Cancellation Service ics_paypal_update_agreement

Transaction Search Service ics_paypal_transaction_search

Get Transaction Details Service ics_paypal_get_txn_details

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

Set Service

The ics_paypal_ec_set service:

 Alerts PayPal that an order is going to occur.

 Returns a session token.

After ics_paypal_ec_set 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 13.

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 Traditional Express Checkout and In-Context Express Checkout,

see "In-Context Express Checkout Flow," page 14.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP 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 paypal_return. If the customer cancels the transaction, the customer is

redirected to the return URL in the field paypal_cancel_return.

Multiple Calls to the Set Service

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

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

call ics_paypal_ec_set again as a follow-on service.

Required Fields

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

request:

 ics_applications

 merchant_id

 merchant_ref_number

 currency

 grand_total_amount or at least one offer line with an amount field

 paypal_return

 paypal_cancel_return

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 ics_paypal_ec_set, you must redirect the customer’s

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

above.

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

have your account configured for this feature. For important information

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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

 paypal_ec_set_request_id

 paypal_ec_set_request_token

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

following fields:

 paypal_billing_type (required)

 paypal_billing_agreement_desc (optional)

 paypal_billing_agreement_custom (optional)

 paypal_payment_type (optional)

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

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

Get Details Service

The ics_paypal_ec_get_details service:

 Returns information about a customer.

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

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

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

 paypal_ec_get_details_address1

 paypal_ec_get_details_address2

 paypal_ec_get_details_city

 paypal_ec_get_details_state

 paypal_ec_get_details_zip

 paypal_ec_get_details_country_code

 paypal_ec_get_details_country_name

 paypal_ec_get_details_address_id

To receive these values, you must do the following:

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

account.

The ics_paypal_ec_get_details service 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 ics_

paypal_ec_get_details even if you do not allow customers to change their

shipping addresses.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

 Contact Cybersource Customer Support to have your Cybersource account

configured to request the billing address.

 Set paypal_request_billing_address to 1 in your request for ics_paypal_ec_set.

If you included offer-level fields in your request for the ics_paypal_ec_set service, the

ics_paypal_ec_get_details service returns offer-level fields in the reply message. These

fields are described in "Offer-Level Reply Fields," page 71.

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

the request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_ec_set_request_id

 paypal_ec_set_request_token

 paypal_token

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

Payment Service

The ics_paypal_ec_do_payment service:

 Obtains the authorization implicitly.

 Returns an order ID and an authorization ID.

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

The Do Payment service sets an authorization as an embedded payment action

parameter in the third API call. When you use the Do 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.

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

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

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

The ics_paypal_ec_do_payment service is used only for standard orders.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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

the request:

 ics_applications

 merchant_id

 merchant_ref_number

 currency

 grand_total_amount or at least one offer line with an amount field

 paypal_customer_email

 paypal_ec_set_request_id

 paypal_ec_set_request_token

 paypal_payer_id

 paypal_token

The following fields are required only if Decision Manager is enabled:

 bill_address1

 bill_city

 bill_country

 bill_state—required only when the country is US or Canada.

 bill_zip—required only when the country is US or Canada.

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

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

Order Setup Service

The ics_paypal_ec_order_setup service:

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

 Returns a transaction ID.

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

have your account configured for this feature. For important information

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

The ics_paypal_ec_order_setup service is used only for custom orders.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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

the request:

 ics_applications

 merchant_id

 merchant_ref_number

 currency

 grand_total_amount or at least one offer line with an amount field

 paypal_customer_email

 paypal_ec_set_request_id

 paypal_ec_set_request_token

 paypal_payer_id

 paypal_token

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

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

Authorization Service

The ics_paypal_authorization 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.

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

request:

 ics_applications

 merchant_id

 paypal_order_id

 merchant_ref_number

 currency

 grand_total_amount

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

have your account configured for this feature. For important information

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

 paypal_customer_email

 customer_email

 A request ID:

 For a custom order: paypal_ec_order_setup_request_id

 For a billing agreement: paypal_do_ref_transaction_request_id

 A request token:

 For a custom order: paypal_ec_order_setup_request_token

 For a billing agreement: paypal_do_ref_transaction_request_token

The following fields are required only if Decision Manager is enabled:

 bill_address1

 bill_city

 bill_country

 bill_state—required only when the country is US or Canada.

 bill_zip—required only when the country is US or Canada.

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

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

Capture Service

The ics_paypal_do_capture 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 ics_paypal_do_capture, you must include the following fields in the

request:

 ics_applications

 merchant_id

 merchant_ref_number

 complete_type—This flag indicates whether it is a full capture or a partial capture.

 currency

 grand_total_amount

 paypal_authorization_id

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

 A request ID:

 For a standard order: paypal_ec_do_payment_request_id

 For a custom order: paypal_authorization_request_id

 A request token:

 For a standard order: paypal_ec_do_payment_request_token

 For a custom order: paypal_authorization_request_token

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

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

Sale Service

A sale consists of calling ics_paypal_ec_do_payment and ics_paypal_do_capture in

the same request. The sale:

 Obtains the authorization.

 Captures all of the authorized amount.

 Returns a transaction ID.

When you request ics_paypal_ec_do_payment and ics_paypal_do_capture in the

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

 ics_applications

 merchant_id

 merchant_ref_number

 complete_type

 currency

 grand_total_amount or at least one offer line with an amount field

 paypal_customer_email

 paypal_ec_set_request_id

 paypal_ec_set_request_token

 paypal_payer_id

 paypal_token

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

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

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

have your account configured for this feature. For important information

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

Create Agreement Service

The ics_paypal_create_agreement service:

 Creates a billing agreement.

 Returns a billing agreement ID.

Before calling ics_paypal_create_agreement:

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

 The billing agreement status returned by ics_paypal_ec_get_details must indicate

that the customer accepted the billing agreement.

When you request ics_paypal_create_agreement, you must include the following fields

in the request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_token

 paypal_ec_set_request_id

 paypal_ec_set_request_token

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

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

Reference Transaction Service

The ics_paypal_do_ref_transaction service uses a billing agreement to process a

payment.

When you request ics_paypal_do_ref_transaction, you must include the following fields

in the request:

 ics_applications

 merchant_id

 merchant_ref_number

 grand_total_amount or at least one offer line with an amount field

 currency

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

have your account configured for this feature. For important information

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

 paypal_billing_agreement_id

 paypal_payment_type

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

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

Authorization Reversal Service

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

following services can be reversed:

 ics_paypal_ec_do_payment

 ics_paypal_ec_order_setup

 ics_paypal_authorization

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

request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_authorization_id

 A request ID:

 For a standard order:

paypal_ec_do_payment_request_id

 For a custom order when reversing an order setup:

paypal_ec_order_setup_request_id

 For a custom order when reversing an authorization:

paypal_authorization_request_id

 A request token:

 For a standard order:

paypal_ec_do_payment_request_token

 For a custom order when reversing an order setup:

paypal_ec_order_setup_request_token

 For a custom order when reversing an authorization:

paypal_authorization_request_token

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

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 SCMP API |

Refund Service

The ics_paypal_refund service:

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

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

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

request:

 ics_applications

 merchant_id

 merchant_ref_number

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

partial refund.

 paypal_capture_id

 paypal_do_capture_request_id—This value determines which capture will be

refunded.

 paypal_do_capture_request_token

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

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

Reauthorization Service

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

authorization is about to expire.

To perform a reauthorization:

Step 1 Call ics_paypal_auth_reversal.

Step 2 Call ics_paypal_ec_do_payment for a standard order or call ics_paypal_authorization

for a custom order.

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

Cancellation Service

The ics_paypal_update_agreement service cancels a billing agreement.

When you request ics_paypal_update_agreement, you must include the following fields

in the request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_billing_agreement_id

 paypal_billing_agreement_status

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

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

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

The ics_paypal_

transaction_search 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 ics_paypal_

transaction_search, you must include the following fields in

the request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_transaction_search_start_date

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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

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

Table 14 Transaction Search Criteria

Criteria Field Name

Customer’s email address paypal_customer_email

Customer’s name: salutation payer_salutation

Customer’s name: first name payer_firstname

Customer’s name: middle name payer_middlename

Customer’s name: last name payer_lastname

Customer’s name: suffix payer_suffix

Date range paypal_transaction_search_end_date

The start date is specified in paypal_transaction_

search_start_date, which is a required field for this

service.

Invoice number paypal_invoice_number

Payment status paypal_payment_status

Receipt ID paypal_receipt_id

Transaction amount grand_total_amount

Transaction currency currency

Transaction ID transaction_id

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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

The ics_paypal_

get_txn_details service returns information about a transaction. When

you request ics_paypal_

get_txn_details, you must include the transaction ID that was

returned by one of these services:

 ics_paypal_ec_do_payment

 ics_paypal_ec_order_setup

 ics_paypal_authorization

 ics_paypal_do_capture

 ics_paypal_refund

 ics_paypal_do_ref_transaction

When you request ics_paypal_

get_txn_details, you must include the following fields in

the request:

 ics_applications

 merchant_id

 merchant_ref_number

 paypal_transaction_id

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

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

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 offers for which the product code is not handling_only, shipping_and_

handling, or shipping_only.

2 Multiplies quantity * amount for each offer identified in step 1.

3 Adds the values that were calculated in step 2.

Example 1 Offers That Cause PayPal to Decline a Transaction

offer0=amount:10.00^quantity:1^product_code:Beverages^product_

name:Fancy Cola^merchant_product_sku:B4859^tax_amount:10^product_

description:Description for Fancy Cola!

offer1=amount:5.00^product_code=shipping_only

offer2=amount:10.00^quantity:1^product_code:coupon^product_

name:Discount^merchant_product_sku:D1000^product_description:1000th

customer discount

Chapter 2 Requesting Services

PayPal Express Checkout Services Using the SCMP API |

CHAPTER

PayPal Express Checkout Services Using the SCMP API | 39

API Fields

Formatting Restrictions

Unless otherwise noted, all of the fields listed are order and case insensitive, and the

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

Order-level and offer-level field names and values must not contain carets (^) or colons

(:). However, they can contain embedded spaces and any other printable characters. If

you use more than one consecutive space, the extra 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 15 Data Type Definitions

Data Type Description

Date and time Format is YYYY-MM-DDThhmmssZ, where:

 T separates the date and the time

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

Greenwich Mean Time (GMT)

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

(10:47:57 p.m.)

Decimal Number that includes a decimal point

Example 23.45, -0.1, 4.0, 90809.0468

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

Nonnegative integer Whole number greater than or equal to zero {0, 1, 2, 3, ...}

Positive integer Whole number greater than zero {1, 2, 3, ...}

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

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Request Fields

Order-Level Request Fields

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

Cybersource.

Table 16 Order-Level Request Fields

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

bill_address1 Credit card billing street address as it appears

in the credit card issuer’s records.

ics_paypal_

authorization

ics_paypal_do_capture

Required only when

Decision Manager is

enabled.

String (60)

bill_city Credit card billing city. ics_paypal_

authorization

ics_paypal_do_capture

Required only when

Decision Manager is

enabled.

String (50)

bill_country Credit card billing country. Use the two-

character ISO Standard Country Codes.

ics_paypal_

authorization

ics_paypal_do_capture

Required only when

Decision Manager is

enabled.

String (2)

bill_state Credit card billing state or province. Use the

State, Province, and Territory Codes for the

United States and Canada.

ics_paypal_

authorization

ics_paypal_do_capture

Required only when

Decision Manager is

enabled AND the

country is US or

Canada.

String (2)

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

bill_zip 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

ics_paypal_

authorization

ics_paypal_do_capture

Required only when

Decision Manager is

enabled AND the

country is US or

Canada.

String (10)

customer_email Customer’s email address. ics_paypal_

authorization (R)

String (256)

customer_ipaddress Customer’s IP address. ics_paypal_

authorization (O)

String (45)

complete_type Indicates whether this is a partial capture or a

complete capture. Possible values:

 Complete: Complete capture

 NotComplete: Partial capture

ics_paypal_do_capture

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

ics_paypal_ec_set (R)

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

ics_paypal_

authorization (R)

ics_paypal_do_capture

(R)

ics_paypal_do_ref_

transaction (R)

ics_paypal_

transaction_search (O)

String (3)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

grand_total_amount Grand total for the order. If shipping costs and

tax charges are known, include them in this

value. If not, 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 ics_paypal_ec_set, ics_paypal_ec_do_

payment, ics_paypal_ec_order_setup, and

ics_paypal_do_ref_transaction, the request

must include either this field or offer0 and the

offer-level field amount. See the information

about offers and grand totals in Getting Started

with Cybersource Advanced for the SCMP

API.

Format:

 Cannot include a currency symbol

 Must include two decimal places

 The decimal separator must be a period (.)

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_

authorization (R)

ics_paypal_do_capture

(R)

ics_paypal_refund (R)

ics_paypal_do_ref_

transaction

(See description)

ics_paypal_

transaction_search (O)

String (15)

ics_applications ICS services to process for the request. At

least one service must be specified in the

request.

Required for all PayPal

Express Checkout

Services

String (255)

link_to_request Value that links the current request to a

previous authorization request for a debit card

or prepaid card. This value is useful when

using multiple payment methods to complete

an order. For more information, see “Partial

Authorizations” in Credit Card Services Using

the SCMP API (PDF | HTML).

String (26) String (30)

merchant_id Your Cybersource merchant ID. Use the same

merchant ID for evaluation, testing, and

production.

Required for all PayPal

Express Checkout

Services

String (30)

merchant_ref_number 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

SCMP API.

Required for all PayPal

Express Checkout

Services

String (50)

payer_firstname Customer’s first name. ics_paypal_

transaction_search (O)

String (25)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

payer_lastname Customer’s last name. ics_paypal_

transaction_search (O)

String (25)

payer_middlename Customer’s middle name. ics_paypal_

transaction_search (O)

String (25)

payer_salutation Customer’s salutation. ics_paypal_

transaction_search (O)

String (20)

payer_suffix Customer’s suffix. ics_paypal_

transaction_search (O)

String (12)

paypal_address_

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 Chapter 1, "Introduction to PayPal

Express Checkout," on 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.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (1)

paypal_authorization_id Unique PayPal authorization identification

number returned in the authorization reply

paypal_authorization_transaction_id field.

ics_paypal_do_capture

(R)

ics_paypal_auth_

reversal (R)

String (19)

paypal_authorization_

request_id

Value of request_id returned from a previous

request for ics_paypal_authorization. This is

the request_id 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.

ics_paypal_do_capture

(See description)

ics_paypal_auth_

reversal

(See description)

String (26)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_authorization_

request_token

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.

ics_paypal_do_capture

(R)

ics_paypal_auth_

reversal (R)

String (256)

paypal_billing_

agreement_custom

Custom annotation field for your own use. ics_paypal_ec_set

(O for billing

agreements; otherwise,

not used)

ics_paypal_update_

agreement (O)

String (256)

paypal_billing_

agreement_desc

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.

ics_paypal_ec_set

(O for billing

agreements; otherwise,

not used)

ics_paypal_update_

agreement (O)

String (127)

paypal_billing_

agreement_id

Identifier for the billing agreement. ics_paypal_update_

agreement (R)

ics_paypal_do_ref_

transaction (R)

String (256)

paypal_billing_

agreement_status

Status of the billing agreement. Possible

values:

 Active: The billing agreement is active.

 Canceled: The billing agreement is

canceled.

ics_paypal_update_

agreement (R)

String (8)

paypal_billing_type Type of billing agreement to create. The only

possible value is

MerchantInitiated

Billing

, which creates a billing agreement

for payments that you initiate.

ics_paypal_ec_set

(R for billing

agreements; otherwise,

not used)

String (25)

paypal_cancel_return URL to which customers are returned if they do

not approve the use of PayPal for payment.

ics_paypal_ec_set (R) String (no

limit)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_capture_id Unique PayPal transaction identification

number returned in the capture reply in the

paypal_do_capture_transaction_id field.

ics_paypal_refund (R) String (17)

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

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

ics_paypal_

authorization (R)

ics_paypal_

transaction_search (O)

String (127)

paypal_desc Description of items the customer is

purchasing.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_order_

setup (O)

ics_paypal_do_ref_

transaction (O)

String (127)

paypal_do_capture_

request_id

Value of request_id returned from a previous

request for ics_paypal_do_capture. When

calling ics_paypal_refund, this is the

request_id of the capture you want to credit.

ics_paypal_refund (R) String (26)

paypal_do_capture_

request_token

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.

ics_paypal_refund (R) String (256)

paypal_do_ref_

transaction_request_id

Value of request_id returned from a previous

request for ics_paypal_do_ref_transaction.

ics_paypal_

authorization (R)

String (26)

paypal_do_ref_

transaction_request_

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.

ics_paypal_

authorization (R)

String (256)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_ec_do_

payment_request_id

Value of request_id returned from a previous

request for ics_paypal_ec_do_payment. This

is the request_id 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.

ics_paypal_do_capture

(See description)

ics_paypal_auth_

reversal

(See description)

String (26)

paypal_ec_do_

payment_request_

token

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.

ics_paypal_do_capture

(R)

ics_paypal_auth_

reversal (R)

String (256)

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

ics_paypal_do_ref_

transaction (O)

Alphanumeric

(2048)

paypal_ec_order_

setup_request_id

Value of request_id returned from a previous

request for ics_paypal_ec_order_setup.

This is the request_id of the order setup you

want to authorize or reverse.

ics_paypal_

authorization (R)

ics_paypal_auth_

reversal

(See description)

String (26)

paypal_ec_order_

setup_request_token

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.

ics_paypal_

authorization (R)

ics_paypal_auth_

reversal (R)

String (256)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_ec_set_

request_id

Value of request_id returned from a previous

request for ics_paypal_ec_set.

ics_paypal_ec_set

(Required unless it is

the first call to ics_

paypal_ec_set)

ics_paypal_ec_get_

details (R)

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

ics_paypal_create_

agreement (R)

String (26)

paypal_ec_set_

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

ics_paypal_ec_set (R)

ics_paypal_ec_get_

details (R)

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

ics_paypal_create_

agreement (R)

String (256)

paypal_hdrbackcolor Background color for the header of the

payment page.

Format: HTML hexadecimal color

ics_paypal_ec_set (O) String (6)

paypal_hdrbordercolor Border color around the header of the payment

page.

Format: HTML hexadecimal color

ics_paypal_ec_set (O) String (6)

paypal_hdrimg URL for the image that will be displayed in the

upper left area of the payment page.

ics_paypal_ec_set (O) String (127)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_invoice_number Your invoice or tracking number. ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_order_

setup (O)

ics_paypal_do_capture

(O)

ics_paypal_do_ref_

transaction (O)

ics_paypal_

transaction_search (O)

String (127)

paypal_lc 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

ics_paypal_ec_set (R) String (2)

paypal_logoimg 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 paypal_hdrimg in

your request, PayPal uses this value and

ignores paypal_hdrimg.

Note Contact Cybersource Customer

Support to have your account configured for

this feature.

ics_paypal_ec_set (O) String (127)

paypal_maxamt 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 (.)

ics_paypal_ec_set (O) String (15)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_noshipping Indicates if 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.

ics_paypal_ec_set (O) String (1)

paypal_note Memo about the refund. PayPal sends this

information to the customer in the notification

email.

ics_paypal_refund (O) String (255)

paypal_order_id Transaction identifier created by PayPal. This

field is returned as follows:

 For a standard order: In paypal_ec_do_

payment_paypal_transaction_id in the

reply from ics_paypal_ec_do_payment.

 For a custom order: In paypal_ec_order_

setup_paypal_transaction_id in the reply

from ics_paypal_ec_order_setup.

ics_paypal_

authorization (O)

String (255)

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

ics_paypal_ec_set (O) Alphabetic

String (30)

paypal_payer_id Unique PayPal customer account identification

number that was returned in the ics_paypal_

ec_get_details reply message.

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

String (13)

paypal_payflowcolor Background color for the payment page.

Format: HTML hexadecimal color

ics_paypal_ec_set (O) String (6)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_

transaction_search (O)

String (20)

paypal_payment_type Indicates whether the payment is instant or

delayed. Possible values:

 echeck

 instant

ics_paypal_ec_set

(O for billing

agreements; otherwise,

not used)

ics_paypal_do_ref_

transaction (R)

String (7)

paypal_receipt_id Receipt identification number.

Format: NNNN-NNNN-NNNN-NNNN

ics_paypal_

transaction_search (O)

String (16)

paypal_

reqconfirmshipping

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.

ics_paypal_ec_set (O)

ics_paypal_do_ref_

transaction (O)

Numeric (1)

paypal_request_billing_

address

Indicates whether to return the customer’s

billing address when you call ics_paypal_ec_

get_details. Possible values:

 0: Do not return the customer’s billing

address.

 1: Return the customer’s billing address.

ics_paypal_ec_set (O) String (1)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_ec_set (R) String (no

limit)

paypal_return_fmf_

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.

ics_paypal_do_ref_

transaction (O)

String (1)

paypal_shipping_

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.

ics_paypal_do_ref_

transaction (O)

String (9)

paypal_soft_descriptor Description that is displayed on the customer’s

account statement.

ics_paypal_do_ref_

transaction (O)

String (256)

paypal_token Timestamped token by which you identify to

PayPal that you are processing this payment

with Express Checkout.

This value is returned by ics_paypal_ec_set

the first time you request the service.

ics_paypal_ec_set

(Required unless it is

the first call to ics_

paypal_ec_set)

ics_paypal_ec_get_

details (R)

ics_paypal_ec_do_

payment (R)

ics_paypal_ec_order_

setup (R)

ics_paypal_create_

agreement (R)

String (20)

paypal_transaction_id Value of paypal_transaction_id returned from

a previous request. This is the paypal_

transaction_id of the transaction for which

you are requesting information.

ics_paypal_

transaction_search (O)

ics_paypal_get_txn_

details (R)

String (17)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_transaction_

search_end_date

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

ics_paypal_

transaction_search (O)

String (20)

paypal_transaction_

search_start_date

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

ics_paypal_

transaction_search (R)

String (20)

promo_code0 Promotion code that enables customers to

apply PayPal promotions to your products

when purchased through PayPal Express

Checkout.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_order_

setup (O)

String (20)

ship_to_address1 First line of the shipping address. ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (100)

ship_to_address2 Second line of the shipping address. ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (100)

ship_to_city City of the shipping address. ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (40)

ship_to_country Country of the shipping address. Use the two-

character ISO Standard Country Codes.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (2)

ship_to_firstname First name of the recipient.

The two name fields, ship_to_firstname and

ship_to_lastname, are concatenated. The

maximum combined size is 32 characters. If

the size exceeds 32 characters, the name is

truncated.

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_set (O)

String (see

description)

ship_to_lastname Last name of the recipient.

The two name fields, ship_to_firstname and

ship_to_lastname, are concatenated. The

maximum combined size is 32 characters. If

the size exceeds 32 characters, the name is

truncated.

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_set (O)

String (see

description)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

ship_to_phone Phone number for the shipping address. ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (20)

ship_to_state State or province of the shipping address. Use

the State, Province, and Territory Codes for the

United States and Canada.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (40)

ship_to_zip 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

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

String (20)

Table 16 Order-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O)

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Offer-Level Request Fields

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

your account configured for this feature.

Table 17 Offer-Level Request Fields

Field Description Used By

(Required (R) /

Optional (O))

Data Type

& Length

amount Per-item price of the product. You must include either

offer0 and this field, or the order-level field grand_

total_amount in your request. See the information

about offers and grand totals in Getting Started with

Cybersource Advanced for the SCMP API.

This value cannot be negative. 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 (.)

Important If this value is less than or equal to zero,

PayPal declines the transaction.

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_do_ref_

transaction

(See description)

Decimal (15)

merchant_

product_sku

Identification code for the product. This field is

required if the product code is not

default or one of

the shipping and handling values.

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_do_ref_

transaction

(See description)

String (127)

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

product_code 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 offer-level fields in your request:

 merchant product SKU

 product name

 quantity

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_do_ref_

transaction

(See description)

String (255)

product_

description

For the log data to be complete, you must include this

field in requests that include offer-level fields.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_order_

setup (O)

ics_paypal_do_ref_

transaction (O)

String (127)

product_name This field is required if the product code is not

default or one of the shipping and handling values.

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_do_ref_

transaction

(See description)

String (127)

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.

ics_paypal_ec_set

(See description)

ics_paypal_ec_do_

payment

(See description)

ics_paypal_ec_order_

setup (See description)

ics_paypal_do_ref_

transaction

(See description)

Nonnegative

integer (10)

Table 17 Offer-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O))

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

tax_amount Total tax to apply to the product. This value cannot be

negative. The tax amount and the offer amount must

be in the same currency.

The tax amount field is additive. For example:

1 You include the following offer lines in your request:

offer0=product_code:electronic_

good^amount:10.00^quantity:1^

product_name:Disc Cleaner^merchant

_product_sku:245237^tax_amount:

0.80

offer1=product_code:electronic_

good^amount:20.00^quantity:1^

product_name:Disc Cleaner^merchant

_product_sku:245237^tax_amount:

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 ics_tax service, see Tax Calculation Service

Using the SCMP API.

ics_paypal_ec_set (O)

ics_paypal_ec_do_

payment (O)

ics_paypal_ec_order_

setup (O)

ics_paypal_do_ref_

transaction (O)

Decimal (15)

Table 17 Offer-Level Request Fields (Continued)

Field Description Used By

(Required (R) /

Optional (O))

Data Type

& Length

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Reply Fields

Naming Conventions for SCMP API Order-Level

Reply Fields

For most SCMP 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 SCMP API services

and the preface to use for each service. In Table 19, "Order-Level Reply Fields," on

page 58, 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 paypal_do_capture_paypal_

receipt_id.

 The Get Details service returns the shipping country in paypal_ec_get_details_ship_

to_country.

The names of most SCMP API reply fields include a preface.

Table 18 Prefaces for SCMP API Reply Fields

Service Name Preface

ics_paypal_auth_reversal paypal_auth_reversal

ics_paypal_authorization paypal_authorization

ics_paypal_create_agreement paypal_create_agreement

ics_paypal_do_capture paypal_do_capture

ics_paypal_do_ref_transaction paypal_do_ref_transaction

ics_paypal_ec_do_payment paypal_ec_do_payment

ics_paypal_ec_get_details paypal_ec_get_details

ics_paypal_ec_order_setup paypal_ec_order_setup

ics_paypal_ec_set paypal_ec_set

ics_paypal_get_txn_details paypal_get_txn_details

ics_paypal_refund paypal_refund

ics_paypal_transaction_search paypal_transaction_search

ics_paypal_update_agreement paypal_update_agreement

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Order-Level Reply Fields

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 Order-Level Reply Fields

Field Description Returned By Data Type &

Length

address_id eBay company that maintains this address.

Possible values:

 eBay

 PayPal

ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (20)

address_status Status of the street address on file with PayPal.

Possible values:

 None

 Confirmed

 Unconfirmed

ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (12)

address1 First line of the street address in the customer’s

billing address.

ics_paypal_ec_get_

details

String (100)

address2 Second line of the street address in the customer’s

billing address.

ics_paypal_ec_get_

details

String (100)

amount Total transaction amount. ics_paypal_ec_

order_setup

ics_paypal_

authorization

String (15)

authorization_id Authorization identification number that was sent

in the request.

ics_paypal_do_

capture

ics_paypal_auth_

reversal

String (19)

auth_avs Indicates the status of the customer’s address.

Possible values:

 1: None

 2: Other

 3: Confirmed

 4: Unconfirmed

ics_paypal_ec_get_

details

Numeric (1)

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

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

city City in the customer’s billing address. ics_paypal_ec_get_

details

String (40)

correlation_id Identifier that can be used for working with PayPal

to investigate issues.

All PayPal Express

Checkout services

String (20)

country_code Code for the country in the customer’s billing

address.

ics_paypal_ec_get_

details

String (2)

country_name Name of the country in the customer’s billing

address.

ics_paypal_ec_get_

details

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.

ics_paypal_ec_

order_setup

ics_paypal_

authorization

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (3)

error_code Identifier that can be used for working with PayPal

to investigate issues.

All PayPal Express

Checkout services

String (10)

* ics_rcode One-digit code that indicates whether the entire

request was successful. See the information about

handling replies in Getting Started with

Cybersource Advanced for the SCMP API.

Possible values:

 -1: An error occurred

 0: The request was declined

 1: The request was successful

All PayPal Express

Checkout services

Integer (1)

* ics_rflag One-word description of the result of the entire

request. See the information about handling

replies in Getting Started with Cybersource

Advanced for the SCMP API.

All PayPal Express

Checkout services

String (50)

* ics_rmsg Message that explains the reply flag ics_rflag. Do

not display this message to the customer, and do

not use this field to write an error handler. See the

information about handling replies in Getting

Started with Cybersource Advanced for the SCMP

API.

All PayPal Express

Checkout services

String (255)

* merchant_ref_number Order reference or tracking number that you

provided in the request. If you included multi-byte

characters in this field in the request, the returned

value might contain corrupted characters.

All PayPal Express

Checkout services

String (50)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

order_id Transaction identifier created by PayPal. ics_paypal_ec_do_

payment

String (255)

parent_transaction_id 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

ics_paypal_do_

capture

ics_paypal_get_

txn_details

String (19)

payer Customer’s email address. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (127)

payer_business Customer’s business name. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (127)

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

character ISO Standard Country Codes.

ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (2)

payer_firstname Customer’s first name. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (25)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

payer_id Customer’s unique PayPal customer account

identification number.

ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

Alphanumeric

string (13)

payer_lastname Customer’s last name. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (25)

payer_middlename Customer’s middle name. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (25)

payer_phone Customer’s contact telephone number.

Field mask for U.S. numbers:

XXX-XXX-XXXX

Field mask for international numbers:

+XXX XXXXXXXX

ics_paypal_ec_get_

details

String (20)

payer_salutation Customer’s salutation. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (20)

payer_status Customer’s status. Possible values:

 verified

 unverified

ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (10)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

payer_suffix Customer’s suffix. ics_paypal_ec_get_

details

ics_paypal_update_

agreement

ics_paypal_get_

txn_details

String (12)

payment_type Indicates whether the payment is instant or

delayed. Possible values:

 none

 echeck

 instant

ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

String (7)

paypal_amount Final amount charged. ics_paypal_ec_

order_setup

ics_paypal_

authorization

ics_paypal_do_ref_

transaction

String (15)

paypal_billing_

agreement_accepted_

status

Indicates if the customer accepted the billing

agreement. Possible values:

 0: Not accepted

 1: Accepted

ics_paypal_ec_get_

details

String (1)

paypal_billing_

agreement_custom

Custom annotation field. ics_paypal_update_

agreement

String (256)

paypal_billing_

agreement_desc

Description of the goods or services associated

with the billing agreement.

ics_paypal_update_

agreement

Alphanumeric

String (127)

paypal_billing_

agreement_id

Identifier for the billing agreement. ics_paypal_create_

agreement

ics_paypal_ec_do_

payment

ics_paypal_update_

agreement

ics_paypal_do_ref_

transaction

String (256)

paypal_billing_

agreement_status

Status of the billing agreement. Possible values:

 Active: The billing agreement is active.

 Canceled: The billing agreement has been

cancelled.

ics_paypal_update_

agreement

String (8)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_exchange_rate Exchange rate if a currency conversion occurred.

The 17 characters include the decimal point.

ics_paypal_do_

capture

ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

Decimal (17)

paypal_fee_amount 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 (,).

ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

ics_paypal_

authorization

ics_paypal_do_

capture

ics_paypal_get_

txn_details

String (9)

paypal_fee_refund_

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 (,).

ics_paypal_refund String (9)

paypal_gross_refund_

amount

Amount of money refunded to the customer. ics_paypal_refund Ask your

PayPal

representative

paypal_invoice_number Your invoice or tracking number. ics_paypal_get_

txn_details

String (127)

paypal_net_refund_

amount

Amount subtracted from PayPal balance of the

customer who is getting the refund.

ics_paypal_refund Ask your

PayPal

representative

paypal_note Memo or note that the customer entered on the

PayPal pages.

ics_paypal_get_

txn_details

String (255)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

paypal_order_time Date-time stamp of the payment.

Format: YYYY-MM-DDTHH:MM:SSZ

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

ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (20)

paypal_payment_

gross_amount

Amount of money refunded to the customer. 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 (,).

ics_paypal_do_

capture

ics_paypal_get_

txn_details

Ask your

PayPal

representative

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_ec_

order_setup

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (20)

paypal_payment_type Indicates whether the payment is instant or

delayed. Possible values:

 none

 echeck

 instant

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (7)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_ec_

order_setup

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

Note To enable the

paypal_pending_

reason field for ics_

paypal_do_

capture, contact

Cybersource

Customer Support

to have your

account configured

for this feature.

String (14)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_ec_

order_setup

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (15)

paypal_receipt_id Receipt identification number.

Format: NNNN-NNNN-NNNN-NNNN

ics_paypal_do_

capture

ics_paypal_get_

txn_details

String (16)

paypal_settle_amount 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 (,).

ics_paypal_get_

txn_details

String (15)

paypal_tax_amount 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 (,).

ics_paypal_ec_do_

payment

ics_paypal_ec_get_

details

ics_paypal_ec_

order_setup

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (9)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_ec_set

ics_paypal_ec_get_

details

ics_paypal_ec_

order_setup

String (20)

paypal_transaction_id Unique PayPal identifier for the transaction. ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

ics_paypal_

authorization

ics_paypal_do_

capture

ics_paypal_refund

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (17)

paypal_transactiontype Indicates whether the payment is instant or

delayed. Possible values:

 cart

 express-checkout

ics_paypal_ec_do_

payment

ics_paypal_ec_

order_setup

ics_paypal_do_

capture

ics_paypal_do_ref_

transaction

ics_paypal_get_

txn_details

String (16)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

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

ics_paypal_

authorization

ics_paypal_get_

txn_details

String (17)

protection_eligibility_

type

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 protection_eligibility_type

field, contact Cybersource Customer Support to

have your account configured for this feature.

ics_paypal_

authorization

ics_paypal_get_

txn_details

String (32)

rcode One-digit code that indicates whether the service

request was successful. See the information about

handling replies in Getting Started with

Cybersource Advanced for the SCMP API.

Possible values:

 -1: An error occurred

 0: The request was declined

 1: The request was successful

All PayPal Express

Checkout services

Integer (1)

rflag One-word description of the result of the service

request. See the information about handling

replies in Getting Started with Cybersource

Advanced for the SCMP API.

All PayPal Express

Checkout services

String (50)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

rmsg Message that explains the reply flag for the

service. Do not display this message to the

customer, and do not use this field to write an error

handler. See the information about handling

replies in Getting Started with Cybersource

Advanced for the SCMP API.

All PayPal Express

Checkout services

String (255)

* request_id Identifier for the request generated by the client. All PayPal Express

Checkout services

String (26)

* request_token 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 SCMP API.

All PayPal Express

Checkout services

String (256)

ship_to_address1 First line of the shipping address. ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (100)

ship_to_address2 Second line of the shipping address. ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (100)

ship_to_city City of the shipping address. ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (40)

ship_to_country Country of the shipping address. Use the two-

character ISO Standard Country Codes.

ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (2)

ship_to_name Name of the recipient. ics_paypal_get_

txn_details

String (32)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Offer-Level Reply Fields

ship_to_phone Phone number for the shipping address. ics_paypal_get_

txn_details

String (20)

ship_to_state State or province of the shipping address. Use the

State, Province, and Territory Codes for the United

States and Canada.

ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (40)

ship_to_zip Postal code for the shipping address. Consists of 5

to 9 digits.

ics_paypal_ec_get_

details

ics_paypal_get_

txn_details

String (20)

state Abbreviation for the state or province in the

customer’s billing address.

ics_paypal_ec_get_

details

String (40)

zip Postal code in the customer’s billing address. ics_paypal_ec_get_

details

String (20)

Table 19 Order-Level 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 SCMP API Order-Level Reply Fields," page 57.

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

your account configured for this feature.

Table 20 Offer-Level Reply Fields

Field Description Returned By Data Type

& Length

amount Per-item price of the product. ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

Decimal (15)

merchant_

product_sku

Identification code for the product. ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

String (127)

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Transaction Search Reply Fields

The ics_paypal_transaction_search 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.

product_code 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

shipping_and_handling line item.

Note If you use a customized value for the product

code, you receive a value of

default in this field.

ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

String (255)

product_

description

The product description is not returned when the

product code is handling_only or shipping_

and_handling

ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

String (127)

product_name The product name is not returned when the product

code is

handling_only or shipping_and_

handling

ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

String (127)

quantity The quantity is not returned when the product code is

handling_only or shipping_and_

handling

ics_paypal_ec_get_

details

ics_paypal_get_txn_

details

Nonnegative

integer (10)

Table 20 Offer-Level Reply Fields (Continued)

Field Description Returned By Data Type

& Length

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

paypal_transaction_search. For example, the Transaction Search service

returns the first transaction’s currency in paypal_transaction_search_

transaction_0_currency. "Transaction Search Example," page 89, shows

what the transaction search reply fields look like in a reply message.

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

Table 21 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.

ics_paypal_

transaction_search

String (3)

transaction_#_

grand_total_

amount

Total transaction amount. ics_paypal_

transaction_search

String (15)

transaction_#_

paypal_

customer_

display_name

Customer’s name as displayed on the PayPal web

pages.

ics_paypal_

transaction_search

String

transaction_#_

paypal_fee_

amount

Fee that PayPal charged for the transaction. ics_paypal_

transaction_search

Decimal

transaction_#_

paypal_net_

amount

Net amount of the transaction. ics_paypal_

transaction_search

Decimal

transaction_#_

paypal_payer_

or_payee_email

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.

ics_paypal_

transaction_search

String (127)

transaction_#_

paypal_

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

ics_paypal_

transaction_search

String (20)

transaction_#_

paypal_

transaction_time

Date and time when PayPal processed the

transaction. This value is in UTC/GMT.

Format: YYYY-MM-DD~HH:MM:SS

where ~ denotes a space.

Example 2012-09-12 17:23:15

ics_paypal_

transaction_search

String (20)

Chapter API Fields

PayPal Express Checkout Services Using the SCMP API |

transaction_#_

paypal_

transaction_

timezone

Time zone for the transaction_#_paypal_

transaction_time value. This value is always

GMT.

ics_paypal_

transaction_search

String (3)

transaction_#_

paypal_

transaction_type

Possible values:

 Currency Conversion (credit)

 Currency Conversion (debit)

 Payment

 Recurring Payment

 Temporary Hold

 Transfer

 Donation

ics_paypal_

transaction_search

String (30)

transaction_#_

transaction_id

Unique PayPal identifier for the transaction. ics_paypal_

transaction_search

String (17)

Table 21 Transaction Search Reply Fields (Continued)

Field Description Returned By Data Type

& Length

CHAPTER

PayPal Express Checkout Services Using the SCMP API | 75

Examples

Billing Agreement Examples

Billing Agreement with Payment

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

services:

 ics_paypal_ec_set

 ics_paypal_ec_get_details

 ics_paypal_ec_do_payment

 ics_paypal_do_capture

Example 2 Request for ics_paypal_ec_set

ics_applications=ics_paypal_ec_set

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_currency=USD

paypal_return=http://www.cybersource.com

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

paypal_billing_agreement_desc=Home Town Newspaper Online*4.99 per month

paypal_billing_agreement_custom=One-year subscription

paypal_billing_type=MerchantInitiatedBilling

paypal_payment_type=instant

grand_total_amount=4.99

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 3 Reply from ics_paypal_ec_set

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_set_rcode=1

paypal_ec_set_rflag=SOK

paypal_ec_set_rmsg=Request was processed successfully.

request_id=1928320121920167904854

request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchant_ref_number=HTNsubscription9647

paypal_ec_set_correlation_id=4lks03uw2lbwxu

paypal_ec_set_paypal_token=EC-2UN29359TV924162S

paypal_ec_set_error_code=93045SLWVO

paypal_ec_set_amount=4.99

Example 4 Request for ics_paypal_ec_get_details

ics_applications=ics_paypal_ec_get_details

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_request_id=1928320121920167904854

paypal_ec_set_request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

paypal_token=EC-2UN29359TV924162S

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 5 Reply from ics_paypal_ec_get_details

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_get_details_rcode=1

paypal_ec_get_details_rflag=SOK

paypal_ec_get_details_rmsg=Request was processed successfully.

request_id=29FJBLS93TBQPSLDGK3H

request_token=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchant_ref_number=HTNsubscription9647

paypal_ec_get_details_paypal_billing_agreement_accepted_status=1

paypal_ec_get_details_correlation_id=sldkf9325sdfsdlkjgj

paypal_ec_get_details_auth_avs=3

paypal_ec_get_details_paypal_token=EC-2UN29359TV924162S

paypal_ec_get_details_error_code=93045SLWVO

paypal_ec_get_details_address_status=Confirmed

paypal_ec_get_details_payer_id=S6D5ETGSVYX94

paypal_ec_get_details_payer_status=verified

paypal_ec_get_details_payer_firstname=Jane

paypal_ec_get_details_payer_lastname=Smith

paypal_ec_get_details_payer_country=US

paypal_ec_get_details_payer=jsmit[email protected]

paypal_ec_get_details_ship_to_name=Jane Smith

paypal_ec_get_details_ship_to_address1=1295 Charleston Rd.

paypal_ec_get_details_ship_to_city=Mountain View

paypal_ec_get_details_ship_to_state=CA

paypal_ec_get_details_ship_to_country=US

paypal_ec_get_details_ship_to_zip=9404

Example 6 Request for ics_paypal_ec_do_payment

ics_applications=ics_paypal_ec_do_payment

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_request_id=1928323124420167904854

paypal_ec_set_request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

paypal_token=EC-2UN29359TV924162S

paypal_customer_email=jsmith@examples.com

paypal_payer_id=S6D5ETGSVYX94

paypal_ec_do_payment_currency=USD

grand_total_amount=4.99

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 7 Reply from ics_paypal_ec_do_payment

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_do_payment_rcode=1

paypal_ec_do_payment_rflag=SOK

paypal_ec_do_payment_rmsg=Request was processed successfully.

request_id=TN10C8B3MHS0AK3BKSGN8

request_token=Crdug4OkpF2Qfd8oXDD0ZE4vpp24

merchant_ref_number=HTNsubscription9647

paypal_ec_do_payment_paypal_billing_agreement_id=3ADOib340UWM8923lf20

paypal_ec_do_payment_correlation_id=sldkf9325sdfsdlkjgj

paypal_ec_do_payment_paypal_token=EC-2UN29359TV924162S

paypal_ec_do_payment_paypal_payment_status=Pending

paypal_ec_do_payment_paypal_transaction_id=2YG99268YE540943P

paypal_ec_do_payment_payment_type=None

paypal_ec_do_payment_paypal_tax_amount=0.00

paypal_ec_do_payment_order_id=O-58X525738C493004E

paypal_ec_do_payment_paypal_transactiontype=expresscheckout

paypal_ec_do_payment_paypal_pending_reason=order

paypal_ec_do_payment_error_code=93045SLWVO

Example 8 Request for ics_paypal_do_capture

ics_applications=ics_paypal_do_capture

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_do_payment_request_id=TN10C8B3MHS0AK3BKSGN8

paypal_ec_do_payment_request_token=Crdug4OkpF2Qfd8oXDD0ZE4vpp24

complete_type=Complete

paypal_authorization_id=2YG99268YE540943P

grand_total_amount=4.99

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Billing Agreement without Payment

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

services:

 ics_paypal_ec_set

 ics_paypal_ec_get_details

 ics_paypal_create_agreement

Example 9 Reply from ics_paypal_do_capture

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_do_capture_rcode=1

paypal_do_capture_rflag=SOK

paypal_do_capture_rmsg=Request was processed successfully.

request_id=FY25W8N9OWC2LE7WOCBU5

request_token=Dtely5OsoW3Pnw0mWVV9x26mll35

merchant_ref_number=HTNsubscription9647

paypal_do_capture_paypal_transaction_id=2SA82969X3543562X

paypal_do_capture_parent_transaction_id=2YG99268YE540943P

paypal_do_capture_authorization_id=2YG99268YE540943P

paypal_do_capture_paypal_payment_status=Completed

paypal_do_capture_error_code=93045SLWVO

paypal_do_capture_correlation_id=gwlbof9325biwflpaj

paypal_do_capture_paypal_payment_type=instant

paypal_do_capture_paypal_payment_gross_amount=4.99

paypal_do_capture_paypal_tax_amount=0.00

paypal_do_capture_paypal_fee_amount=0.36

paypal_do_capture_paypal_transactiontype=expresscheckout

Example 10 Request for ics_paypal_ec_set

ics_applications=ics_paypal_ec_set

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_currency=USD

paypal_return=http://www.cybersource.com

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

paypal_billing_agreement_desc=Home Town Newspaper Online*4.99 per month

paypal_billing_agreement_custom=One-year subscription

paypal_billing_type=MerchantInitiatedBilling

paypal_payment_type=instant

grand_total_amount=0

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 11 Reply from ics_paypal_ec_set

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_set_rcode=1

paypal_ec_set_rflag=SOK

paypal_ec_set_rmsg=Request was processed successfully.

request_id=1928320121920167904854

request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchant_ref_number=HTNsubscription9647

paypal_ec_set_correlation_id=4lks03uw2lbwxu

paypal_ec_set_paypal_token=EC-2UN29359TV924162S

paypal_ec_set_error_code=93045SLWVO

paypal_ec_set_amount=0

Example 12 Request for ics_paypal_ec_get_details

ics_applications=ics_paypal_ec_get_details

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_request_id=1928320121920167904854

paypal_ec_set_request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

paypal_token=EC-2UN29359TV924162S

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 13 Reply from ics_paypal_ec_get_details

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_get_details_rcode=1

paypal_ec_get_details_rflag=SOK

paypal_ec_get_details_rmsg=Request was processed successfully.

request_id=29FJBLS93TBQPSLDGK3H

request_token=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchant_ref_number=HTNsubscription9647

paypal_ec_get_details_paypal_billing_agreement_accepted_status=1

paypal_ec_get_details_correlation_id=sldkf9325sdfsdlkjgj

paypal_ec_get_details_auth_avs=3

paypal_ec_get_details_paypal_token=EC-2UN29359TV924162S

paypal_ec_get_details_error_code=93045SLWVO

paypal_ec_get_details_address_status=Confirmed

paypal_ec_get_details_payer_id=S6D5ETGSVYX94

paypal_ec_get_details_payer_status=verified

paypal_ec_get_details_payer_firstname=Jane

paypal_ec_get_details_payer_lastname=Smith

paypal_ec_get_details_payer_country=US

paypal_ec_get_details_payer=jsmit[email protected]

paypal_ec_get_details_ship_to_name=Jane Smith

paypal_ec_get_details_ship_to_address1=1295 Charleston Rd.

paypal_ec_get_details_ship_to_city=Mountain View

paypal_ec_get_details_ship_to_state=CA

paypal_ec_get_details_ship_to_country=US

paypal_ec_get_details_ship_to_zip=94043

Example 14 Request for ics_paypal_create_agreement

ics_applications=ics_paypal_create_agreement

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_ec_set_request_id=1928320121920167904854

paypal_ec_set_request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

paypal_token=EC-2UN29359TV924162S

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Reference Transaction

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

payment by calling these services:

 ics_paypal_do_ref_transaction

 ics_paypal_authorization

 ics_paypal_do_capture

Example 15 Reply from ics_paypal_create_agreement

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_create_agreement_rcode=1

paypal_create_agreement_rflag=SOK

paypal_create_agreement_rmsg=Request was processed successfully.

request_id=TN10C8B3MHS0AK3BKSGN8

request_token=Crdug4OkpF2Qfd8oXDD0ZE4vpp24

merchant_ref_number=HTNsubscription9647

paypal_create_agreement_paypal_billing_agreement_

id=3ADOib340UWM8923lf20

Example 16 Request for ics_paypal_do_ref_transaction

ics_applications=ics_paypal_do_ref_transaction

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

currency=USD

grand_total_amount=4.99

paypal_billing_agreement_id=3ADOib340UWM8923lf20

paypal_payment_type=instant

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 17 Reply from ics_paypal_do_ref_transaction

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_do_ref_transaction_rcode=1

paypal_do_ref_transaction_rflag=SOK

paypal_do_ref_transaction_rmsg=Request was processed successfully.

request_id=023mbdgil2spfkgjqdbvn

request_token=slbiw9345BJldbodflBNQCPE1409D9k

merchant_ref_number=HTNsubscription9647

paypal_do_ref_transaction_correlation_id=4lks03uw2lbwxu

paypal_do_ref_transaction_paypal_token=EC-2UN29359TV924162S

paypal_do_ref_transaction_error_code=93045SLWVO

paypal_do_ref_transaction_amount=4.99

paypal_do_ref_transaction_currency=USD

paypal_do_ref_transaction_paypal_amount=4.99

paypal_do_ref_transaction_paypal_billing_agreement_id=

3ADOib340UWM8923lf20

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

paypal_do_ref_transaction_paypal_payment_status=Completed

paypal_do_ref_transaction_paypal_payment_type=instant

paypal_do_ref_transaction_paypal_pending_reason=none

paypal_do_ref_transaction_paypal_reason_code=none

paypal_do_ref_transaction_paypal_tax_amount=0.00

paypal_do_ref_transaction_paypal_transactiontype=express-checkout

paypal_do_ref_transaction_paypal_transaction_id=htnsubw30bwlbnq2

Example 18 Request for ics_paypal_authorization

ics_applications=ics_paypal_authorization

paypal_order_id=58X525738C493004E

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

currency=USD

grand_total_amount=4.99

paypal_do_ref_transaction_request_id=023mbdgil2spfkgjqdbvn

paypal_do_ref_transaction_request_token=slbiw9345BJldbodflBNQCPE1409D9k

paypal_customer_email=jsmith@example.com

[email protected]

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 19 Reply from ics_paypal_authorization

ics_rcode=1

ics_rmsg=Request was processed successfully.

ics_rflag=SOK

merchant_ref_number=HTNsubscription9647

request_id=49gks2og0g12wrg879aergsk

request_token=SLGQ30B235b0XCV0lskb2369awopSgm

paypal_authorization_rcode=1

paypal_authorization_rmsg=Request was processed successfully.

paypal_authorization_rflag=SOK

paypal_authorization_amount=4.99

paypal_authorization_currency=USD

paypal_authorization_paypal_transaction_id=3GT12375C398240X

paypal_authorization_paypal_amount=4.99

paypal_authorization_correlation_id=r2lvp9325sdfsdlkjgj

paypal_authorization_error_code=sboe93045

Example 20 Request for ics_paypal_do_capture

ics_applications=ics_paypal_do_capture

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

currency=USD

grand_total_amount=4.99

complete_type=Complete

paypal_authorization_request_id=49gks2og0g12wrg879aergsk

paypal_authorization_request_token=SLGQ30B235b0XCV0lskb2369awopSgm

paypal_authorization_id=9XT12375C2469923X

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Cancellation Example

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

update_agreement service.

Example 21 Reply from ics_paypal_do_capture

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

merchant_ref_number=HTNsubscription9647

paypal_do_capture_rcode=1

paypal_do_capture_rflag=SOK

paypal_do_capture_rmsg=Request was processed successfully.

request_id=203948106391278015965

request_token=FFv9VEdZAOGh084W7RJzIIzHUTUL

paypal_do_capture_paypal_payment_type=instant

paypal_do_capture_paypal_payment_gross_amount=4.99

paypal_do_capture_paypal_tax_amount=0.00

paypal_do_capture_currency=USD

paypal_do_capture_paypal_fee_amount=0.36

paypal_do_capture_amount=4.99

paypal_do_capture_paypal_transactiontype=cart

paypal_do_capture_paypal_transaction_id=4M8612956X2810426

paypal_do_capture_parent_transaction_id=9XT12375C2469923X

paypal_do_capture_authorization_id=0YU23486D3570034Y

paypal_do_capture_paypal_payment_status=Completed

paypal_do_capture_correlation_id=r2lvp9325sdfsdlkjgj

paypal_do_capture_error_code=sboe93045

Example 22 Request for ics_paypal_update_agreement

ics_applications=ics_paypal_update_agreement

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

paypal_billing_agreement_id=3ADOib340UWM8923lf20

paypal_billing_agreement_status=Canceled

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 23 Reply from ics_paypal_update_agreement

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_update_agreement_rcode=1

paypal_update_agreement_rflag=SOK

paypal_update_agreement_rmsg=Request was processed successfully.

request_id=LRMB83bzwl39b8qen

request_token=Ydlt020bjUPZ4bwpc6937prh

merchant_ref_number=HTNsubscription9647

paypal_update_agreement_address_status=Confirmed

paypal_update_agreement_payer=jsm[email protected]

paypal_update_agreement_payer_business=Home Town Newspaper

paypal_update_agreement_payer_country=US

paypal_update_agreement_payer_firstname=Jane

paypal_update_agreement_payer_lastname=Smith

paypal_update_agreement_payer_id=S6D5ETGSVYX94

paypal_update_agreement_payer_status=verified

paypal_update_agreement_paypal_billing_agreement_custom=

One-year subscription

paypal_update_agreement_paypal_billing_agreement_desc=

Home Town Newspaper Online*4.99 per month

paypal_update_agreement_paypal_billing_agreement_

id=3ADOib340UWM8923lf20

paypal_update_agreement_paypal_billing_agreement_status=Canceled

paypal_update_agreement_correlation_id=4lks03uw2lbwxu

paypal_update_agreement_error_code=93045SLWVO

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Offer-Level Examples

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

your account configured for this feature.

Example 24 Request for ics_paypal_ec_set

ics_applications=ics_paypal_ec_set

merchant_id=HomeTownBooks

merchant_ref_number=HTBorder9647

currency=USD

paypal_return=http://www.cybersource.com

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

offer0=product_code:books^product_name:Merriam-Webster Dictionary

^merchant_product_sku:23456^quantity:1^amount:22.00^tax_amount:1.10

offer1=product_code:books^product_name:Handbook of English Grammar

^merchant_product_sku:23458^quantity:1^amount:24.00^tax_amount:1.20

offer2=product_code:books^product_name:Roget's Thesaurus^merchant_

product_sku:23450^quantity:1^amount:16.00^tax_amount:0.80

offer3=product_code:coupon^product_name:New Customer^merchant_product_

sku:97531^quantity:1^amount:3.00

offer4=product_code:shipping_and_handling^amount:7.95

Example 25 Reply from ics_paypal_ec_set

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_ec_set_rcode=1

paypal_ec_set_rflag=SOK

paypal_ec_set_rmsg=Request was processed successfully.

request_id=KPTRWUMC123893lsng

request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

merchant_ref_number=HTBorder9647

paypal_ec_set_paypal_token=349GJlk2jk34993

paypal_ec_set_correlation_id=5lks03uw3lawxz

paypal_ec_set_error_code=911245SVtsO

Example 26 Request for ics_paypal_ec_get_details

ics_applications=ics_paypal_ec_get_details

merchant_id=HomeTownBooks

merchant_ref_number=HTBorder9647

paypal_ec_set_request_id=KPTRWUMC123893lsng

paypal_ec_set_request_token=Aeuvj6IjRRjVhjIZWEEvhhf8jZL4YX/I20gRk

paypal_token=349GJlk2jk34993

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 27 Reply from ics_paypal_ec_get_details

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

request_id=RZ34980sctj2

request_token=Bxwje3Ijb7OskjK6HGG0XF3vllnoyf

merchant_ref_number=HTBorder9647

paypal_ec_get_details_rcode=1

paypal_ec_get_details_rflag=SOK

paypal_ec_get_details_rmsg=Request was processed successfully.

paypal_ec_get_details_paypal_token=349GJlk2jk34993

paypal_ec_get_details_correlation_id=6ksz03np4lbwxy

paypal_ec_get_details_error_code=822236PXnw3

paypal_ec_get_details_auth_avs=3

paypal_ec_get_details_address_status=Confirmed

paypal_ec_get_details_payer_id=S6D5ETGSVYX94

paypal_ec_get_details_payer_status=verified

paypal_ec_get_details_payer_firstname=Jane

paypal_ec_get_details_payer_lastname=Smith

paypal_ec_get_details_payer_country=US

paypal_ec_get_details_payer=jsmit[email protected]

paypal_ec_get_details_ship_to_name=Jane Smith

paypal_ec_get_details_ship_to_address1=1295 Charleston Rd.

paypal_ec_get_details_ship_to_city=Mountain View

paypal_ec_get_details_ship_to_state=CA

paypal_ec_get_details_ship_to_country=US

paypal_ec_get_details_ship_to_zip=94043

paypal_ec_get_details_paypal_tax_amount=3.10

offer0=product_code:default^product_name:Merriam-Webster Dictionary

^merchant_product_sku:23456^quantity:1^amount:22.00

offer1=product_code:default^product_name:Handbook of English Grammar

^merchant_product_sku:23458^quantity:1^amount:24.00

offer2=product_code:default^product_name:Roget's Thesaurus^merchant_

product_sku:23450^quantity:1^amount:16.00

offer3=product_code:coupon^product_name:New Customer^merchant_product_

sku:97531^quantity:1^amount:3.00

offer4=product_code:shipping_and_handling^amount:7.95

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Transaction Search Example

Example 28 Request for ics_paypal_transaction_search

merchant_id=HomeTownNewspaper

merchant_ref_number=HTNsubscription9647

ics_applications=ics_paypal_transaction_search

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

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

paypal_customer_email=jsmith@example.com

paypal_transaction_id=93N51798SX666845X

paypal_invoice_number=0001529

grand_total_amount=5.00

currency=USD

paypal_payment_status=Success

payer_firstname=Jane

payer_lastname=Smith

Chapter Examples

PayPal Express Checkout Services Using the SCMP API |

Example 29 Reply from ics_paypal_transaction_search

merchant_ref_number=HTNsubscription9647

request_id=3485988938400181552773

request_token=AhjrLwSRefOhK9P3yQ0KIJp7HBMVhNPMrTnpa4sA/H2H

ics_rcode=1

ics_rflag=SOK

ics_rmsg=Request was processed successfully.

paypal_transaction_search_rcode=1

paypal_transaction_search_rflag=SOK

paypal_transaction_search_rmsg=Request was processed successfully.

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

paypal_transaction_search_transaction_0_paypal_transaction_timezone=GMT

paypal_transaction_search_transaction_0_transaction_type=Payment

paypal_transaction_search_transaction_0_paypal_payer_or_payee_email=jsmith@example.com

paypal_transaction_search_transaction_0_paypal_customer_display_name=Jane Smith

paypal_transaction_search_transaction_0_paypal_transaction_id=93N51798SX666845X

paypal_transaction_search_transaction_0_paypal_payment_status=Completed

paypal_transaction_search_transaction_0_grand_total_amount=5.00

paypal_transaction_search_transaction_0_currency=USD

paypal_transaction_search_transaction_0_paypal_fee_amount=-0.45

paypal_transaction_search_transaction_0_paypal_net_amount=4.55

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

paypal_transaction_search_transaction_1_paypal_transaction_timezone=GMT

paypal_transaction_search_transaction_1_transaction_type=Authorization

paypal_transaction_search_transaction_1_paypal_payer_or_payee_email=jsmith@example.com

paypal_transaction_search_transaction_1_paypal_customer_display_name=Jane Smith

paypal_transaction_search_transaction_1_paypal_transaction_id=8KV00008PR858651B

paypal_transaction_search_transaction_1_paypal_payment_status=Completed

paypal_transaction_search_transaction_1_grand_total_amount=5.00

paypal_transaction_search_transaction_1_currency=USD

paypal_transaction_search_transaction_1_paypal_fee_amount=0.00

paypal_transaction_search_transaction_1_paypal_net_amount=5.00

CHAPTER

PayPal Express Checkout Services Using the SCMP 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 SCMP API | 111

Product Codes

The following table lists the values you can use for the product code in the product_code

offer-level 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 SCMP API | 93

Reply Flags

The following table lists the PayPal Express Checkout reply flags returned by the SCMP

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

Advanced for the SCMP API for a discussion of replies and reply flags.

Because Cybersource can add reply fields, reply codes (rcode), reply flags

(rflag), and reply messages (rmsg) 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 reply flag value to determine the

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

Table 24 Reply Flags

Reply Flag Description

SOK Successful transaction.

DMISSINGFIELD The request is missing one or more required fields.

DINVALIDDATA One of the following:

 One or more fields in the request contain invalid data.

 General decline by PayPal. Possible action: request that the

customer selects a different form of payment at the PayPal

web

site.

 There is a problem with your Cybersource merchant configuration.

Possible action: do not resend the request. Contact Customer

Support to correct the configuration problem.

ESYSTEM System error. You must design your transaction management system

to include a way to correctly handle Cybersource system errors. The

error might indicate a valid Cybersource system error, or it might

indicate a PayPal rejection because of some type of invalid data. In

either case, Cybersource recommends that you do not design your

system to endlessly retry sending a transaction in the case of a

system error. See the documentation for the Cybersource client you

are using for important information about how to handle system errors

and retries.

Chapter Reply Flags

PayPal Express Checkout Services Using the SCMP API |

ETIMEOUT Error: The request was received but there was a server timeout. This

error does not include timeouts between the client and the server.

Possible action: To avoid duplicating the transaction, do not resend

the request until you have reviewed the transaction status in the

Business Center. See the documentation for your Cybersource client

for information about how to handle retries in the case of system

errors.

DPAYMENTREFUSED PayPal rejected the transaction.

Table 24 Reply Flags (Continued)

Reply Flag Description

PayPal Express Checkout Services Using the SCMP API | February 2021 95

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 33

authorization reversals

defined 18

requesting 33

Authorization Service 29

authorizations

delayed 15

requesting 29

reversing 33

billing agreement IDs, defined 10

billing agreements

canceling 35

creating 32

defined 17

updating 35

billing information, requesting 26

Buyer Complaint Process 20

Cancellation Service 35

cancellations

defined 18

requesting 35

capture IDs, defined 10

Capture Service 30

captures

delayed 15

requesting 30

characters, special 39

chargebacks 20

check reference numbers 21

checkout methods, defined 9

consumer dispute rights 20

Create Agreement Service 32

credits, requesting 34

currency codes 91

custom orders, defined 15

customer information, requesting 26

data types 39

date and time formats 39

delayed authorizations, defined 15

delayed captures, defined 15

dispute rights 20

examples 75

Get Details Service 26

Get Transaction Details Service 37

GMT 39

Appendix Index

PayPal Express Checkout Services Using the SCMP API |

honor periods, defined 10

immediate partial sales, defined 15

In-Context Express Checkout 12

naming conventions for reply fields 57

offer-level fields

in replies 71

in requests 54

order IDs, defined 10

Order Setup Service 28

order setup, requesting 28

order tracking 21

payment method, defined 9

Payment Service 27

payments, requesting 27

PayPal accounts, setting up 11

prerequisites 11

processor transaction identifiers 21

product codes 92

promo codes 52

protection policy 20

Reauthorization Service 34

reauthorizations

defined 18

procedure 34

reconciliation IDs 21

redirection URLs 24

Reference Transaction Service 32

reference transactions

defined 17

requesting 32

Appendix Index

PayPal Express Checkout Services Using the SCMP API |

Refund Service 34

refunds

defined 18

requesting 34

regular orders, defined 14

reply fields 57

reply flags 93

reports 19

request IDs 21

request-level fields 40

requirements 11

reversals

defined 18

requesting 33

Sale Service 31

sales

defined 14

procedure 31

Seller Protection Policy 20

session tokens, defined 10

Set Service 24

setting up orders 28

shortcut method, defined 9

special characters 39

split shipments 30

standard orders, defined 14

time formats 39

Traditional Express Checkout 12

transaction reference numbers 21

Transaction Search Service 35

transactions

requesting details about 37

search reply fields 72

searching for 35

updating billing agreements 35

URLs for live transactions 24

Appendix Index

PayPal Express Checkout Services Using the SCMP API |

UTC 39