Field

Description

Used By (Required (R) / Optional (O)

Data Type & Length

billTo_city

City of the billing address.

payPalAuthorization
Service

payPalDoPayment
Service

Required only if Decision Manager is enabled.

String (50)

billTo_country

Country of the billing address. Use the two-character ISO Standard Country Codes.

payPalAuthorization
Service

payPalDoPayment
Service

Required only if Decision Manager is enabled.

String (2)

* billTo_email

Customer’s email address.

payPalAuthorization Service (R)

String (256)

billTo_ipAddress

Customer’s IP address.

payPalAuthorization Service (O)

String (45)

billTo_postalCode

Postal code for the billing address. The postal code must consist of 5 to 9 digits.

When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]

Example  12345-6789

When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]

Example  A1B 2C3

payPalAuthorization
Service

payPalDoPayment
Service

Required only if Decision Manager is enabled AND the billing country is US or Canada.

String (10)

billTo_state

State or province of the billing address. Use the State, Province, and Territory Codes for the United States and Canada.

payPalAuthorization
Service

payPalDoPayment
Service

Required only if Decision Manager is enabled AND the billing country is US or Canada.

String (2)

billTo_street1

First line of the billing street address.

payPalAuthorization
Service

payPalDoPayment
Service

Required only if Decision Manager is enabled.

String (60)

completeType

Indicates whether this is a partial capture or a complete capture. Possible values:

nComplete: Complete capture

nNotComplete: Partial capture

payPalDoPayment
Service (R)

String (12)

currency

Currency code for one of the PayPal transactional currencies. See Currency Codes.

Note  PayPal can add currencies at any time. For an up-to- list of currencies supported by PayPal, contact your PayPal representative.

Important  To request transactions in currencies other than CNY for customers located in China, contact Cybersource Customer Support to have your account configured for this functionality.

payPalTransaction
SearchService (O)

String (3)

endDate

Date and time at which to end the search. The date must be in UTC/GMT.

Format: YYYY-MM-DDTHH:MM:SSZ

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

payPalTransaction
SearchService (O)

String (20)

grandTotalAmount

Grand total for the entire order.

Format:

nCannot include a currency symbol

nMust include two decimal places

nThe decimal separator must be a period (.)

payPalTransaction
SearchService (O)

String (15)

invoiceNumber

Your invoice or tracking number. This value must be unique.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

payPalEcOrderSetup Service (O)

payPalDoCapture
Service (O)

payPalDoRef
TransactionService (O)

payPalTransaction
SearchService (O)

String (127)

* item_#_productCode

Type of product. You can set this field to a value that you create or one of the predefined values listed in Product Codes. The default value is default.

If you set this field to a value other than default or one of the shipping and handling values, you must also include these item-level fields in your request:

nproduct name

nproduct SKU

nquantity

See Numbered Elements.

Note  To enable item-level fields, contact Cybersource Customer Support to have your account configured for this feature.

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalDoRef
TransactionService (See description)

String (255)

* item_#_productDescription

For the log data to be complete, you must include this field in requests that include item-level fields. See Numbered Elements.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

payPalEcOrderSetup
Service (O)

payPalDoRef
TransactionService (O)

String (127)

* item_#_productName

This field is required if the product code is not default or one of the shipping and handling values. See Numbered Elements.

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalDoRef
TransactionService (See description)

String (127)

* item_#_productSKU

Identification code for the product. This field is required if the product code is not default or one of the shipping and handling values. See Numbered Elements.

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalDoRef
TransactionService (See description)

String (127)

* item_#_quantity

The default for this field is 1. This field is required if the product code is not default or one of the shipping and handling values. See Numbered Elements.

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalDoRef
TransactionService (See description)

Nonnegative integer (10)

* item_#_taxAmount

Total tax to apply to the product. This value cannot be negative. The tax amount and the unit price must be in the same currency. See Numbered Elements.

The tax amount field is additive. For example:

1You send one item with a unit price of 10.00 and a tax amount of 0.80, and you send another item with a unit price of 20.00 and a tax amount of 1.60.

2The total amount authorized will be 32.40, not 30.00 with 2.40 of tax included.

If you want to include the tax amount and also request the taxService service, see Tax Calculation Service Using the Simple Order API.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

payPalEcOrderSetup
Service (O)

payPalDoRef
TransactionService (O)

String (15)

* item_#_unitPrice

Per-item price of the product. You must include either this field or purchaseTotals_grandTotalAmount in your request. See Numbered Elements. Also see the information about items and grand totals in Getting Started with CyberSource Advanced for the Simple Order API.

This value must not exceed the equivalent of 10,000 USD in any currency. This value cannot be negative.

Format:

nCannot include a currency symbol

nMust include two decimal places

nThe decimal separator must be a period (.)

Important  If this value is less than or equal to zero, PayPal declines the transaction.

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalDoRef
TransactionService (See description)

String (15)

* linkToRequest

Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information, see “Partial Authorizations” in .

String (26)

String (30)

* merchantID

Your Cybersource merchant ID. Use the same merchant ID for evaluation, testing, and production.

Required for all PayPal Express Checkout services.

String (30)

* merchantReference
Code

Order reference number or tracking number that you generate. Cybersource recommends that you send a unique value for each transaction so that you can perform meaningful searches for the transaction. See the information about tracking orders in Getting Started with CyberSource Advanced for the Simple Order API.

Required for all PayPal Express Checkout services

String (50)

payerFirstname

Customer’s first name.

payPalTransaction
SearchService (O)

String (25)

payerLastname

Customer’s last name.

payPalTransaction
SearchService (O)

String (25)

payerMiddlename

Customer’s middle name.

payPalTransaction
SearchService (O)

String (25)

payerSalutation

Customer’s salutation.

payPalTransaction
SearchService (O)

String (20)

payerSuffix

Customer’s suffix.

payPalTransaction
SearchService (O)

String (12)

paymentStatus

Possible values:

nDenied: You denied the payment. You can deny a payment only if the payment was pending.

nPending: The payment is pending. To find out why the payment is pending, request payPalGetTxnDetailsService and look at the value for the paypalPendingReason field in the reply message.

nProcessing: The payment is being processed.

nReversed: 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.

nSuccess: The payment was completed and the funds were successfully added to your account balance.

payPalTransaction
SearchService (O)

String (20)

paypalAddress
Override

Customer-supplied address sent in the SetExpressCheckout request rather than the address on file with PayPal for this customer.

Note  You can use this field only with the payment method, not with the shortcut method. See Introduction to PayPal Express Checkout, for a description of the PayPal methods.

Possible values:

n1: Display the customer-supplied address.

n0 (default): Display the address on file with PayPal. The customer cannot edit this address.

payPalEcSetService (O)

String (1)

paypalAuthorizationId

Unique PayPal authorization identification number.

For the payPalDoCaptureService, use the number returned in the authorization reply in the payPalAuthorizationReply_transactionId field.

For payPalAuthReversalService, use the number returned in the payPalEcOrderSetupReply_transactionId field.

payPalDoCapture
Service (R)

payPalAuthReversal
Service (R)

String (19)

paypalAuthorization RequestID

Value of requestID returned from a previous request for payPalAuthorizationService. This is the requestID of the authorization you want to capture or reverse.

If you request the authorization and capture services together, you do not need to provide a request ID for the capture request.

payPalDoCapture
Service (See description)

payPalAuthReversal
Service (See description)

String (26)

paypalAuthorization RequestToken

Request token returned from a previous Authorization request. This is the request token from the authorization you want to capture or reverse. If you request the authorization and capture services together, you do not need to provide a request token for the capture request.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalDoCapture
Service (R)

payPalAuthReversal
Service (R)

String (256)

paypalBilling
AgreementCustom

Custom annotation field for your own use.

payPalEcSetService
(O for billing agreements; otherwise, not used)

payPalUpdate
AgreementService (O)

String (256)

paypalBilling
AgreementDesc

Description of the goods or services associated with the billing agreement. PayPal recommends that the description include a brief summary of the billing agreement terms and conditions.

Example  9.99 per month for 2 years.

payPalEcSetService
(O for billing agreements; otherwise, not used)

payPalUpdate
AgreementService (O)

Alphanumeric String (127)

paypalBilling
AgreementId

Identifier for the billing agreement.

payPalUpdate
AgreementService (R)

payPalDoRef
TransactionService (R)

String (256)

paypalBilling
AgreementStatus

Status of the billing agreement. Possible values:

nActive: The billing agreement is active.

nCanceled: The billing agreement is canceled.

payPalUpdate
AgreementService (R)

String (8)

paypalBillingType

Type of billing agreement to create. The only possible value is MerchantInitiated
Billing, which creates a billing agreement for payments that you initiate.

payPalEcSetService
(R for billing agreements; otherwise, not used)

String (25)

paypalCancelReturn

URL to which customers are returned if they do not approve the use of PayPal for payment.

payPalEcSetService (R)

String (no limit)

paypalCaptureId

Unique PayPal transaction identification number returned in the capture reply in the payPalDoCaptureReply_transactionId field.

payPalRefundService (R)

String (17)

paypalCustomerEmail

Email address of the customer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page.

payPalEcSetService (O)

payPalEcDoPayment
Service (R)

payPalEcOrderSetup Service (R)

payPalAuthorization Service (R)

payPalTransaction
SearchService (O)

String (127)

paypalDesc

Description of items the customer is purchasing.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

payPalEcOrderSetup Service (O)

payPalDoRef
TransactionService (O)

String (127)

paypalDoCapture
RequestID

Value of requestID returned from a previous request for paypalDoCaptureService. When calling payPalRefundService, this is the requestID of the capture you want to credit.

payPalRefundService (R)

String (26)

paypalDoCapture
RequestToken

Request token returned from a previous Do Capture request. This is the request token from the capture you want to credit.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalRefundService (R)

String (256)

paypalDoRef
TransactionRequestID

Value of requestID returned from a previous request for payPalDoRefTransactionService.

payPalAuthorization
Service (R)

String (26)

paypalDoRef
TransactionRequest
Token

Request token returned from a previous Do Reference Transaction request.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalAuthorization
Service (R)

String (256)

paypalEcDoPayment
RequestID

Value of requestID returned from a previous request for payPalEcDoPaymentService. This is the requestID of the payment you want to capture or reverse.

If you request the payment and capture services together, you do not need to provide a request ID for the capture request.

payPalDoCapture
Service (See description)

payPalAuthReversal
Service (See description)

String (26)

paypalEcDoPayment
RequestToken

Request token returned from a previous Do Payment request. This is the request token from the payment you want to capture or reverse. If you request the payment and capture services together, you do not need to provide a request token for the capture request.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalDoCapture
Service (R)

payPalAuthReversal
Service (R)

String (256)

paypalEcNotifyUrl

URL to which your Instant Payment Notification (IPN) is sent. If you do not include this value, the notification URL in your merchant account will be used, if one exists.

payPalDoRef
TransactionService (O)

Alphanumeric (2048)

paypalEcOrderSetup RequestID

Value of requestID returned from a previous request for payPalEcOrderSetupService. This is the requestID of the order setup you want to authorize or reverse.

payPalAuthorization Service (R)

payPalAuthReversal Service (See description)

String (26)

paypalEcOrderSetup RequestToken

Request token returned from a previous Order Setup request. This is the request token from the order setup you want to authorize or reverse.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalAuthorization Service (R)

payPalAuthReversal Service (R)

String (256)

paypalEcSetRequestID

Value of requestID returned from a previous request for payPalEcSetService.

payPalEcSetService (Required unless it is the first call to payPalEcSetService)

payPalEcGetDetails
Service (R)

payPalEcDoPayment
Service (R)

payPalEcOrderSetup Service (R)

payPalCreate
AgreementService (R)

String (26)

paypalEcSetRequest
Token

Request token returned from a previous Set request.

The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.

payPalEcSetService (Required unless it is the first call to payPalEcSetService)

payPalEcGetDetails
Service (R)

payPalEcDoPayment Service (R)

payPalEcOrderSetup Service (R)

payPalCreate
AgreementService (R)

String (256)

paypalHdrbackcolor

Background color for the header of the payment page.

Format: HTML hexadecimal color

payPalEcSetService (O)

String (6)

paypalHdrbordercolor

Border color around the header of the payment page.

Format: HTML hexadecimal color

payPalEcSetService (O)

String (6)

paypalHdrimg

URL for the image that will be displayed in the upper left area of the payment page.

payPalEcSetService (O)

String (127)

paypalLc

Locale of pages displayed by PayPal during Express Checkout.

Possible values:

nAU: Australia

nDE: Germany

nES: Spain

nFR: France

nGB: United Kingdom

nIT: Italy

nUS (default): United States

payPalEcSetService (O)

String (2)

paypalLogoimg

URL for an image that PayPal displays on the payment form. This field enables you to add your logo or other image to the PayPal payment form.

If you provide this value and paypalHdrimg in your request, PayPal uses this value and ignores paypalHdrimg.

Note  Contact Cybersource Customer Support to have your account configured for this feature.

payPalEcSetService (O)

String (127)

paypalMaxamt

Expected maximum total amount of the entire order, including shipping costs and tax charges. This value must not exceed the equivalent of 10,000 USD in any currency.

Format:

nCannot include a currency symbol

nMust include two decimal places

nThe decimal separator must be a period (.)

payPalEcSetService (O)

String (15)

paypalNoshipping

Indicates whether the shipping address should be displayed on the PayPal web pages. Possible values:

n0 (default): Shipping address fields should be displayed.

n1: Shipping address fields should not be displayed.

payPalEcSetService (O)

String (1)

paypalNote

Memo about the refund. PayPal sends this information to the customer in the notification email.

payPalRefundService (O)

String (255)

paypalOrderId

Transaction identifier created by PayPal. This field is returned:

nFor a standard order: In the payPalEcDoPaymentReply_transactionId in the reply from payPalEcDoPaymentService.

nFor a custom order: In the payPalEcOrderSetupReply_transactionId in the reply from payPalEcOrderSetupService.

payPalAuthorization
Service (O)

String (255)

paypalPagestyle

Sets the Custom Payment Page Style for payment pages associated with this button or link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you choose when adding or editing the page style from the Profile tab of the My Account tab of your PayPal account.

payPalEcSetService (O)

Alphabetic String (30)

paypalPayerId

Unique PayPal customer account identification number that was returned in the payPalEcGetDetailsService reply message.

payPalEcDoPayment
Service (R)

payPalEcOrderSetup Service (R)

String (13)

paypalPayflowcolor

Background color for the payment page.

Format: HTML hexadecimal color

payPalEcSetService (O)

String (6)

paypalPaymentType

Indicates whether the payment is instant or delayed. Possible values:

necheck

ninstant

paypalEcSetService
(O for billing agreements; otherwise, not used)

payPalDoRef
TransactionService (R)

String (7)

paypalReceiptId

Receipt identification number.

Format: NNNN-NNNN-NNNN-NNNN

payPalTransaction
SearchService (O)

String (16)

paypalReqconfirm
shipping

Indicates if you require the customer’s shipping address on file with PayPal to be a confirmed address. Possible values:

n0 (default): Shipping address need not be confirmed.

n1: Shipping address must be confirmed.

payPalEcSetService (O)

payPalDoRef
TransactionService (O)

String (1)

paypalReturn

URL to which the customer’s browser returns after leaving PayPal.

Note  It is essential that this be the correct URL or you will receive an error.

payPalEcSetService (R)

String (no limit)

paypalReturnFmf
Details

Indicates whether or not to return to you the results that were returned by Fraud Management Filters (FMF). By default, you do not receive this information. Possible values:

n0 (default): Do not return FMF results.

n1: Return FMF results.

payPalDoRef
TransactionService (O)

String (1)

paypalShipping
Discount

Shipping discount for the order. This value:

nMust not exceed the equivalent of 10,000 USD in any currency.

nCannot include a currency symbol.

If a decimal separator is used, it must be a period (.) regardless of the currency. If a thousands separator is used, it must be a comma (,) regardless of the currency.

payPalDoRef
TransactionService (O)

String (9)

paypalSoftDescriptor

Description that is displayed on the customer’s account statement.

payPalDoRef
TransactionService (O)

String (256)

paypalToken

Timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. This value is returned by payPalEcSetService the first time you request the service.

payPalEcSetService (Required unless it is the first call to payPalEcSetService)

payPalEcGetDetails
Service (R)

payPalEcDoPayment
Service (R)

payPalEcOrderSetup Service (R)

payPalCreate
AgreementService (R)

String (20)

promoCode0

Promotion code that enables customers to apply PayPal promotions to your products when purchased through PayPal Express Checkout.

payPalEcSetService (O)

payPalEcDoPayment Service (O)

payPalEcOrderSetup Service (O)

String (20)

* purchaseTotals_currency

Currency code for one of the PayPal transactional currencies. See Currency Codes.

Note  PayPal can add currencies at any time. For an up-to- list of currencies supported by PayPal, contact your PayPal representative.

Important  To request transactions in currencies other than CNY for customers located in China, contact Cybersource Customer Support to have your account configured for this functionality.

payPalEcSetService (R)

payPalEcDoPayment
Service (R)

payPalEcOrderSetup
Service (R)

payPalAuthorization Service (R)

payPalDoCapture
Service (R)

payPalDoRef
TransactionService (R)

String (3)

* purchaseTotals_grandTotalAmount

Grand total for the entire order. If you know the shipping costs and tax amounts, include them in this value. If you do not know the shipping costs and tax amounts, this value should be the subtotal for the order. This value must not exceed the equivalent of 10,000 USD in any currency. This value cannot be negative.

For payPalEcSetService, payPalEcDo
PaymentService, payPalEcOrderSetup
Service, and payPalDoRefTransaction
Service, the request must include either this field or item_0_unitPrice. See the information about items and grand totals in Getting Started with CyberSource Advanced for the Simple Order API.

Format:

nCannot include a currency symbol

nMust include two decimal places

nThe decimal separator must be a period (.)

payPalEcSetService (See description)

payPalEcDoPayment
Service (See description)

payPalEcOrderSetup
Service (See description)

payPalAuthorization Service (R)

payPalDoCapture
Service (R)

payPalRefundService (R)

payPalDoRef
TransactionService (See description)

String (15)

requestBillingAddress

Indicates whether to return the customer’s billing address when you call payPalEcGetDetailsService. Possible values:

n0: Do not return the customer’s billing address.

n1: Return the customer’s billing address.

payPalEcSetService (O)

String (1)

run

Indicates whether to include the service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Required for all PayPal Express Checkout Services

String (5)

* shipTo_city

City of the shipping address.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (40)

* shipTo_country

Country of the shipping address. Use the two-character ISO Standard Country Codes.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (2)

* shipTo_firstName

First name of the recipient.

payPalEcDoPayment
Service (O)

payPalEcSetService (O)

String (15)

* shipTo_lastName

Last name of the recipient.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (15)

* shipTo_phone
Number

Phone number for the shipping address.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (20)

* shipTo_postalCode

Postal code for the shipping address. The postal code must consist of 5 to 9 digits.

When the shipping country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]

Example  12345-6789

When the shipping country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]

Example  A1B 2C3

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (20)

* shipTo_state

State or province of the shipping address. Use the State, Province, and Territory Codes for the United States and Canada.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (40)

* shipTo_street1

First line of the shipping address. 

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (100)

* shipTo_street2

Second line of the shipping address.

payPalEcSetService (O)

payPalEcDoPayment
Service (O)

String (100)

startDate

Date and time at which to start the search. The date must be in UTC/GMT.

Format: YYYY-MM-DDTHH:MM:SSZ

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

payPalTransaction
SearchService (R)

String (20)

transactionID

Value of transactionId returned from a previous request. This is the transactionId of the transaction for which you are requesting information.

payPalTransaction
SearchService (O)

payPalGetTxnDetails
Service (R)

String (17)

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