Request Fields

Naming Conventions for Simple Order API Request Fields

 

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

For most Simple Order API request fields, the field name that you use in your code must be prefaced with the name of the service that is being called followed by an underscore
( _ ). In the following table, an asterisk (*) before a field name indicates that you should not preface the field name with the service name.

Examples:

■	Use this field to include the capture ID in a Refund service request payPalRefundService_paypalCaptureId.

■	Use this field to set the return URL in a Set service request payPalEcSetService_paypalReturn.

Request Field Descriptions

 

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

 

Table 16

Request Fields

Field	Description	Used By (Required (R) / Optional (O)	Data Type & Length
billTo_city	City of the billing address.	payPalAuthorization Service payPalDoPayment Service Required only if Decision Manager is enabled.	String (50)
billTo_country	Country of the billing address. Use the two-character ISO Standard Country Codes.	payPalAuthorization Service payPalDoPayment Service Required only if Decision Manager is enabled.	String (2)
* billTo_email	Customer’s email address.	payPalAuthorization Service (R)	String (256)
billTo_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: ■ Complete: Complete capture ■ NotComplete: Partial capture	payPalDoPayment Service (R)	String (12)
currency	Currency code for one of the PayPal transactional currencies. See Appendix C, Currency Codes. 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: ■ Cannot include a currency symbol ■ Must include two decimal places ■ The decimal separator must be a period (.)	payPalTransaction SearchService (O)	String (15)
invoiceNumber	Your invoice or tracking number. This value must be unique.	payPalEcSetService (O) payPalEcDoPayment Service (O) payPalEcOrderSetup Service (O) payPalDoCapture Service (O) payPalDoRef TransactionService (O) payPalTransaction SearchService (O)	String (127)
* item_#_productCode	Type of product. You can set this field to a value that you create or one of the predefined values listed in Appendix D, Product Codes. The default value is default. If you set this field to a value other than default or one of the shipping and handling values, you must also include these item-level fields in your request: ■ product name ■ product SKU ■ quantity See Numbered Elements. 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: 1 You send one item with a unit price of 10.00 and a tax amount of 0.80, and you send another item with a unit price of 20.00 and a tax amount of 1.60. 2 The total amount authorized will be 32.40, not 30.00 with 2.40 of tax included. If you want to include the tax amount and also request the taxService service, see Tax Calculation Service Using the Simple Order API.	payPalEcSetService (O) payPalEcDoPayment Service (O) payPalEcOrderSetup Service (O) payPalDoRef TransactionService (O)	String (15)
* 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: ■ Cannot include a currency symbol ■ Must include two decimal places ■ The decimal separator must be a period (.) Important If this value is less than or equal to zero, PayPal declines the transaction.	payPalEcSetService (See description) payPalEcDoPayment Service (See description) payPalEcOrderSetup Service (See description) payPalDoRef TransactionService (See description)	String (15)
* linkToRequest	Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information, see “Partial Authorizations” in Credit Card Services Using the Simple Order API (PDF | HTML).	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: ■ Denied: You denied the payment. You can deny a payment only if the payment was pending. ■ Pending: The payment is pending. To find out why the payment is pending, request payPalGetTxnDetailsService and look at the value for the paypalPendingReason field in the reply message. ■ Processing: The payment is being processed. ■ Reversed: The payment was reversed as the result of a chargeback or other type of reversal. The funds were removed from your account balance and returned to the buyer. ■ Success: The payment was completed and the funds were successfully added to your account balance.	payPalTransaction SearchService (O)	String (20)
paypalAddress Override	Customer-supplied address sent in the SetExpressCheckout request rather than the address on file with PayPal for this customer. Note You can use this field only with the payment method, not with the shortcut method. See Introduction to PayPal Express Checkout, for a description of the PayPal methods. Possible values: ■ 1: Display the customer-supplied address. ■ 0 (default): Display the address on file with PayPal. The customer cannot edit this address.	payPalEcSetService (O)	String (1)
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: ■ Active: The billing agreement is active. ■ Canceled: The billing agreement is canceled.	payPalUpdate AgreementService (R)	String (8)
paypalBillingType	Type of billing agreement to create. The only possible value is MerchantInitiated Billing, which creates a billing agreement for payments that you initiate.	payPalEcSetService (R for billing agreements; otherwise, not used)	String (25)
paypalCancelReturn	URL to which customers are returned if they do not approve the use of PayPal for payment.	payPalEcSetService (R)	String (no limit)
paypalCaptureId	Unique PayPal transaction identification number returned in the capture reply in the payPalDoCaptureReply_transactionId field.	payPalRefundService (R)	String (17)
paypalCustomerEmail	Email address of the customer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page.	payPalEcSetService (O) payPalEcDoPayment Service (R) payPalEcOrderSetup Service (R) payPalAuthorization Service (R) payPalTransaction SearchService (O)	String (127)
paypalDesc	Description of items the customer is purchasing.	payPalEcSetService (O) payPalEcDoPayment Service (O) payPalEcOrderSetup Service (O) payPalDoRef TransactionService (O)	String (127)
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: ■ AU: Australia ■ DE: Germany ■ ES: Spain ■ FR: France ■ GB: United Kingdom ■ IT: Italy ■ US (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: ■ Cannot include a currency symbol ■ Must include two decimal places ■ The decimal separator must be a period (.)	payPalEcSetService (O)	String (15)
paypalNoshipping	Indicates whether the shipping address should be displayed on the PayPal web pages. Possible values: ■ 0 (default): Shipping address fields should be displayed. ■ 1: Shipping address fields should not be displayed.	payPalEcSetService (O)	String (1)
paypalNote	Memo about the refund. PayPal sends this information to the customer in the notification email.	payPalRefundService (O)	String (255)
paypalOrderId	Transaction identifier created by PayPal. This field is returned: ■ For a standard order: In the payPalEcDoPaymentReply_transactionId in the reply from payPalEcDoPaymentService. ■ For a custom order: In the payPalEcOrderSetupReply_transactionId in the reply from payPalEcOrderSetupService.	payPalAuthorization Service (O)	String (255)
paypalPagestyle	Sets the Custom Payment Page Style for payment pages associated with this button or link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you choose when adding or editing the page style from the Profile tab of the My Account tab of your PayPal account.	payPalEcSetService (O)	Alphabetic String (30)
paypalPayerId	Unique PayPal customer account identification number that was returned in the payPalEcGetDetailsService reply message.	payPalEcDoPayment Service (R) payPalEcOrderSetup Service (R)	String (13)
paypalPayflowcolor	Background color for the payment page. Format: HTML hexadecimal color	payPalEcSetService (O)	String (6)
paypalPaymentType	Indicates whether the payment is instant or delayed. Possible values: ■ echeck ■ instant	paypalEcSetService (O for billing agreements; otherwise, not used) payPalDoRef TransactionService (R)	String (7)
paypalReceiptId	Receipt identification number. Format: NNNN-NNNN-NNNN-NNNN	payPalTransaction SearchService (O)	String (16)
paypalReqconfirm shipping	Indicates if you require the customer’s shipping address on file with PayPal to be a confirmed address. Possible values: ■ 0 (default): Shipping address need not be confirmed. ■ 1: Shipping address must be confirmed.	payPalEcSetService (O) payPalDoRef TransactionService (O)	String (1)
paypalReturn	URL to which the customer’s browser returns after leaving PayPal. Note It is essential that this be the correct URL or you will receive an error.	payPalEcSetService (R)	String (no limit)
paypalReturnFmf Details	Indicates whether or not to return to you the results that were returned by Fraud Management Filters (FMF). By default, you do not receive this information. Possible values: ■ 0 (default): Do not return FMF results. ■ 1: Return FMF results.	payPalDoRef TransactionService (O)	String (1)
paypalShipping Discount	Shipping discount for the order. This value: ■ Must not exceed the equivalent of 10,000 USD in any currency. ■ Cannot include a currency symbol. If a decimal separator is used, it must be a period (.) regardless of the currency. If a thousands separator is used, it must be a comma (,) regardless of the currency.	payPalDoRef TransactionService (O)	String (9)
paypalSoftDescriptor	Description that is displayed on the customer’s account statement.	payPalDoRef TransactionService (O)	String (256)
paypalToken	Timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. This value is returned by payPalEcSetService the first time you request the service.	payPalEcSetService (Required unless it is the first call to payPalEcSetService) payPalEcGetDetails Service (R) payPalEcDoPayment Service (R) payPalEcOrderSetup Service (R) payPalCreate AgreementService (R)	String (20)
promoCode0	Promotion code that enables customers to apply PayPal promotions to your products when purchased through PayPal Express Checkout.	payPalEcSetService (O) payPalEcDoPayment Service (O) payPalEcOrderSetup Service (O)	String (20)
* purchaseTotals_currency	Currency code for one of the PayPal transactional currencies. See Appendix C, 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: ■ Cannot include a currency symbol ■ Must include two decimal places ■ The decimal separator must be a period (.)	payPalEcSetService (See description) payPalEcDoPayment Service (See description) payPalEcOrderSetup Service (See description) payPalAuthorization Service (R) payPalDoCapture Service (R) payPalRefundService (R) payPalDoRef TransactionService (See description)	String (15)
requestBillingAddress	Indicates whether to return the customer’s billing address when you call payPalEcGetDetailsService. Possible values: ■ 0: Do not return the customer’s billing address. ■ 1: Return the customer’s billing address.	payPalEcSetService (O)	String (1)
run	Indicates whether to include the service in your request. Possible values: ■ true: Include the service in your request. ■ false (default): Do not include the service in your request.	Required for all PayPal Express Checkout Services	String (5)
* shipTo_city	City of the shipping address.	payPalEcSetService (O) payPalEcDoPayment Service (O)	String (40)
* shipTo_country	Country of the shipping address. Use the two-character ISO Standard Country Codes.	payPalEcSetService (O) payPalEcDoPayment Service (O)	String (2)
* shipTo_firstName	First name of the recipient.	payPalEcDoPayment Service (O) payPalEcSetService (O)	String (15)
* shipTo_lastName	Last name of the recipient.	payPalEcSetService (O) payPalEcDoPayment Service (O)	String (15)
* shipTo_phone Number	Phone number for the shipping address.	payPalEcSetService (O) payPalEcDoPayment Service (O)	String (20)
* shipTo_postalCode	Postal code for the shipping address. The postal code must consist of 5 to 9 digits. When the shipping country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example 12345-6789 When the shipping country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space] [numeric][alpha][numeric] Example A1B 2C3	payPalEcSetService (O) payPalEcDoPayment Service (O)	String (20)
* 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.