Request Fields

Order-Level Request Fields

 

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

 

Table 15

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

Offer-Level Request Fields

 

To enable offer-level fields, contact CyberSource Customer Support to have your account configured for this feature.

 

Table 16

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