The following table lists the request-level fields for ics_paypal_button_create. The table indicates whether to use each field when creating a regular payment or billing agreement button.
Table 15 Button Create Request-Level Fields
Request-Level Field Description Type of
Button bill_city City of the billing address. Both Required String (50) bill_country Country of the billing address. Use the
two-character ISO codes. See the Support Center for a list of codes.
Both Required String (2)
bill_state State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes.
Both Required if country is U.S. or Canada
String (2)
bill_zip Postal code for the billing address. The postal code must consist of 5 to 9 digits.
If the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
Both Required if country is U.S. or Canada
String (10)
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
button_type Type of button to create. Use one of the following values:
buy: Regular payment button (PayPal’s Buy Now button)
preapproved_billing_
agreement: Billing agreement button
shopping_cart: PayPal’s Shopping Cart button
Note CyberSource’s preferred solution if you are creating a button for a regular payment is the buy button. Instructions for creating a shopping_cart button are included in Chapter 5, "Creating a Shopping Cart Button," on page 108.
All Required String (30)
currency This becomes the value for the currency_
code variable in the button. This is the currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only.
Regular payment
Required String (5)
customer_email Customer’s email address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]).
Both Optional String
(255)
customer_firstname Customer’s first name. Both Required String (60) customer_lastname Customer’s last name. Both Required String (60) freight_amount This becomes the value for the shipping
variable in the button. This is the total freight amount for the order. If you include this field, grand_total_amount is required.
This value overrides any profile-based shipping charge you have set. See
"Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details.
Regular payment
Optional Decimal (15) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
grand_total_amount This becomes the value for the amount variable in the button. This is the grand total for the order. You 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.
ics_applications ICS services to process for the request. Both Required 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 details, see the information about partial authorizations in Credit Card Services Using the SCMP API.
Regular payment
Optional String (26)
merchant_id Your CyberSource merchant ID. Use the same merchant_id for evaluation, testing, and production.
Both Required String (30)
merchant_ref_number Merchant-generated order reference or tracking number. CyberSource suggests that you use a unique value for each order or billing agreement. See the information about order tracking in Getting Started with CyberSource Advanced.
Both Required String (50)
offer0...N Offers (line items of the order) for the request.
You must include either offer0 and the offer-level field amount, or the request-offer-level field grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced.
paypal_amount CyberSource suggests you do NOT use this PayPal HTML variable in your request for a regular payment button as you will already be specifying a grand_total_amount or offer-level amount which will be used to populate PayPal’s amount variable in the button. See
"PayPal’s HTML Variables for a Regular Payment Button," page 72 for more information.
Neither See description
N/A Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
paypal_cancel_return URL of the Web page to show the customer if the customer cancels the regular PayPal payment, for example: http://
cancel.example.com.
Customer’s email address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]).
Both Optional String
(255)
paypal_handling Do NOT use this field if you are using freight_amount or if you have an offer with product_code= handling_only. CyberSource populates the handling variable in the button based on your values for these fields.
If you are not using freight_amount or an offer for handling, paypal_handling becomes the value for the handling variable in the button.
This is a flat handling charge for the order.
The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details.
Regular payment
Optional Decimal (15)
paypal_item_name This becomes the value for the item_name variable in the button. This is the description of the item. If omitted, the customer will see a field that they can use to enter a description of the item.
Note Although CyberSource has a similar API field (offer-level field product_name), the item_name variable will NOT be populated based on CyberSource’s product_
name field. You may include both paypal_
item_name and product_name in the request.
Regular payment
Optional String (127) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
paypal_item_number This becomes the value for the item_
number variable in the button. It is not displayed to the customer, but it is passed back to you upon completion of the payment.
If omitted, it is not passed back to you.
Note Although CyberSource has a similar API field (the offer-level field merchant_
product_sku), the item_number variable in the button will NOT be populated based on CyberSource’s merchant_product_sku field. You may include both paypal_item_
number and merchant_product_sku in the request.
Regular payment
Optional String (127)
paypal_lc Locale (language) for the billing agreement pages. Use the two-character ISO country codes.
Defines the starting day of the monthly billing cycle. Use a value from 1 to 31. For example, if you set the value to 15, then the monthly billing cycle is from January 15 to February 15, and so on. If you do not provide a value, the monthly billing cycle corresponds to the calendar month.
Billing agreement
Optional Integer (2)
paypal_mp_desc A brief description of the goods or services offered to the customer. Although it is optional, CyberSource recommends that you provide this field. The customer sees this on the page when approving the billing
agreement, in the email confirmation from PayPal when a billing agreement is created or updated, in the transaction detail history for each preapproved payment, and in the email confirmation from PayPal when a
preapproved payment is processed.
Billing agreement
Optional String (no length limit) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
paypal_mp_error Displays an error on the first page of the agreement flow (which the customer sees when they log in to the PayPal site to approve the agreement) indicating that the customer has a problem with their PayPal account.
Include this field in the request if you have received an indication from PayPal that the customer needs to update their account to fulfill payment. Use one of the following values:
paypal_mp_max Maximum amount that you can withdraw from the customer's account for a preapproved payment.
Billing agreement
Required Decimal (15)
paypal_mp_max_edit Whether the customer can edit the monthly maximum billing amount (paypal_mp_max).
Use one of the following values:
0 (default): No, the customer cannot edit the value
1: Yes, the customer can edit the value
Billing agreement
Optional Decimal (1)
paypal_mp_max_min The lowest payment amount the customer is allowed to enter when editing the paypal_
mp_max value. Can be specified only if paypal_mp_max_edit=1.
Billing agreement
Optional Decimal (15)
paypal_mp_pay_type The type of PayPal payment funding source you want the customer to use. Use one of the following values:
A currency amount tested against PayPal's risk and fraud models but not charged to the customer. You receive the result of this test in the mp_test_result HTML variable in the reply POST from PayPal. See "Reply Variables for Creating a Billing Agreement,"
page 141.
Billing agreement
Optional Decimal (15) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
paypal_quantity This becomes the value for the quantity variable in the button. This is the quantity of items to be purchased If omitted, the value defaults to 1 and does not show in the payment flow. Make sure to include this if you are providing the paypal_shipping2 field.
Note Although CyberSource has a similar API field (the offer-level field quantity), the quantity variable in the button will NOT be populated based on CyberSource’s quantity field. Any value you pass here will be displayed as the quantity value in the button.
paypal_return After a customer approves a regular payment or a billing agreement at PayPal’s site, they are returned to a URL at your Web site, such as: http://success.example.com. CyberSource suggests that you set the default URL for regular payments, and you use the API field override for billing agreements. Most likely you will have a different return URL for billing agreements.
Note This value overrides the value you have configured to use with PayPal’s Auto Return. See "Enabling Auto Return,"
page 32.
Both Optional String
(255)
paypal_rm Method of the FORM submission by which PayPal returns data to your Web site. Use one of the following values:
0 (default): POST Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
paypal_shipping Do NOT use this field if you are using freight_amount or if you have an offer with product_code=shipping_only or shipping_and_handling. CyberSource populates the shipping variable in the button based on your values for these fields.
If you are not using freight_amount or an offer for shipping and handling, paypal_
shipping becomes the value for the shipping variable in the button.
This is a flat shipping charge for the order.
The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based handling charge you have set. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details.
Regular payment
Optional Decimal (15)
paypal_shipping2 This becomes the value for the shipping2 variable in the button. This is the cost of shipping each additional item beyond the first item. PayPal multiplies this value by the number of items in the order minus one (paypal_quantity -1) and then adds it to the values for the shipping variable and the handling variable in the button to give the total shipping and handling charge they display to the customer. See "Specifying Shipping and Handling Charges for a Regular Payment Button," page 74 for more details.
Regular payment
Optional Decimal (15) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
paypal_tax Do NOT use this field if you are using the total_tax_amount field or the offer-level tax_
amount field. CyberSource populates the tax variable in the button based on your values for these fields.
If you are not using total_tax_amount or an offer-level tax_amount field, paypal_tax becomes the value for the tax variable in the button.
This is a flat tax charge for the order. The value is NOT multiplied by the number of items in the order (paypal_quantity). The value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 75 for more details. the quantity at PayPal’s site. They will see a quantity field that they must complete. If omitted or set to 0, the customer will not be able to edit the quantity, and a default quantity of 1 will be used.
Regular payment
Optional Non-negative integer (1)
ship_to_address1 First line of the address to which to ship the product.
Regular payment
Optional (1, 2) String (60)
ship_to_address2 Second line of the address to which to ship the product.
Regular payment
Optional (2) String (60)
ship_to_city City to which to ship the product. Regular payment
Optional (1, 2) String (50)
ship_to_country Country to which to ship the product. Use the two-character ISO codes. See the Support Center for a list of codes.
Regular payment
Optional (2) String (2)
ship_to_firstname First name of person receiving the product. Regular payment
Optional (2) String (60)
ship_to_lastname Last name of person receiving the product. Regular payment
Optional (2) String (60)
ship_to_state State or province to which to ship the product.
Use the two-character codes. See the Support Center for a list of valid codes.
Regular payment
Optional (2, 3) String (2) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.
ship_to_zip Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
If the shipping country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If the shipping country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
Regular payment
Optional (2, 3) String (10)
shipping_method Shipping method for the product. For example, FEDEX.
Regular payment
Optional String (10)
timeout Number of seconds the system waits before the transaction times out. The default is 110 seconds.
Both Optional Positive
integer (3)
total_tax_amount This becomes the value for the tax variable in the button.This is the total tax for the order.
If you include this field, grand_total_amount is required.
This value overrides any profile-based tax charge you have set. See "Specifying Tax for a Regular Payment Button," page 75 for more details.
Regular payment
Optional Decimal (15) Table 15 Button Create Request-Level Fields (Continued)
Request-Level Field Description Type of
Button
(1) Required if any shipping information is included.
(2) Optional, but CyberSource encourages you to send the shipping address to increase chances that the transaction will be covered under PayPal’s Seller Protection Policy. See "Sending the Shipping Address for a Regular Payment Button," page 74.
(3) Required if ship_to_country is US or CA.