The following table describes the reply flags for ics_paypal_button_create. The reply flags you receive are the same for either type of button.
paypal_button_
create_time
Time of the button creation request. The format is YYYY-MM-DDThhmmssZ. For example, 2003-08-11T224757Z is equalto August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC.
Date and time (20)
paypal_button_
create_trans_ref_no
Reference number for the transaction that you use to reconcile your transactions.
String (60)
paypal_button_create_
unencrypted_form_data
Unencrypted version of the button. String (no
length limit) request_id Unique identifier for the request generated by the client. String (26) request_token Request token data created by CyberSource for each reply. The
field is an encoded string that contains no confidential
information such as an account or card verification number. The string can contain a maximum of 256 characters.
For more information, see the information about request tokens in Getting Started with CyberSource Advanced.
String (256) Table 17 Button Create Reply Fields (Continued)
Reply Field Description Data Type &
Length
Table 18 Button Create Reply Flags Reply Flag Description
DINVALIDDATA Data provided is not consistent with the request. For example, you requested a product with negative cost.
DMISSINGFIELD The request is missing a required field.
ESYSTEM System error. See the documentation for your CyberSource client (for important information about how to handle system errors and retries.
ETIMEOUT The request timed out.
SOK The transaction was successful.
Processing a Preapproved Payment
After the customer has accepted the billing agreement, you may process preapproved payments according to the agreement. Use ics_paypal_preapproved_payment to process each payment.
To request the service, send a request with ics_applications=ics_paypal_
preapproved_payment. In the paypal_mp_id field you must include the customer's billing agreement identifier that you received when the customer accepted the billing agreement. See the description of mp_id in "Reply Variables for Creating a Billing Agreement," page 141. See Appendix B, "Examples for the SCMP API," on page 128 for example requests and replies.
The only other ICS service that you can call with ics_paypal_preapproved_payment is ics_tax. See the Tax Calculation Implementation Guide.
Request-Level Fields
The following table lists the request-level fields for ics_paypal_preapproved_payment.
Table 19 Preapproved Payment Request-Level Fields
Request-Level Field Description Required/
Optional
Data Type
& Length
bill_city City of the billing address. 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.
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.
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
Required if country is U.S. or Canada
String (10)
currency Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only.
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]).
Optional String (255)
customer_firstname Customer’s first name. Required String (60)
customer_lastname Customer’s last name. Required String (60)
grand_total_amount 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.
See description
Decimal (15)
ics_applications ICS services to process for the request. 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.
Optional String (26)
merchant_id Your CyberSource merchant ID. Use the same merchant_id for evaluation, testing, and production.
Required String (30)
merchant_ref_number Merchant-generated order reference or tracking number.
See the information about order tracking in Getting Started with CyberSource Advanced.
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-level field grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced.
See description
String (50)
paypal_customer_
Customer’s email address, including the full domain name. The field must be submitted in the form [email protected] (for example, [email protected]).
Optional String (255)
paypal_email_subject Subject line of the confirmation email that will be sent to the customer.
Optional String (no length limit)
paypal_item_name Name of purchased item. Optional String (no
length limit) paypal_item_number Reference number of purchased item. Optional String (no
length limit) paypal_memo Text entered by the customer in the Note field during
enrollment.
Optional String (no length limit) Table 19 Preapproved Payment Request-Level Fields (Continued)
Request-Level Field Description Required/
Optional
Data Type
& Length
Offer-Level Fields
The following table describes the offer-level fields for ics_paypal_preapproved_
payment.
paypal_payment_type The type of PayPal payment funding source to use. Use one of the following values:
Any (default): Any payment type is acceptable
EcheckOnly: eCheck
InstantOnly: Instant only
Make sure to provide the value exactly as shown above.
Optional String (11)
timeout Number of seconds the system waits before the transaction times out. The default is 110 seconds.
Optional Positive integer (3) Table 19 Preapproved Payment Request-Level Fields (Continued)
Request-Level Field Description Required/
Optional
Data Type
& Length
Table 20 Preapproved Payment Offer-Level Fields
Offer-Level Field Description Required/
Optional
Data Type
& Length amount Per-item price of the product. You must include either
this field or grand_total_amount in your request. See the information about offers and grand totals in Getting Started with CyberSource Advanced. This value cannot be negative.
You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places.
See description
Decimal (15)
merchant_product_sku Product’s identifier code Optional String (30) product_code Type of product. The default value is default. See
"Product Codes," page 152 for a list of valid values.
Optional String (30)
product_name Product’s name. Optional String (30)
Reply Fields
The following table lists the reply fields for ics_paypal_preapproved_payment.
quantity Quantity of the product being purchased. The default value is 1. Required if product_code for the offer is NOT default, stored_value, or one of the values related to shipping and/or handling.
See description
Non-negative integer (10)
tax_amount Total tax to apply to the product. This value cannot be negative.
The tax_amount field is additive. For example, if you send the following offer lines:
offer0=amount:10.00^quantity:1^tax_
amount:0.80
offer1=amount:20.00^quantity:1^tax_
amount:1.60
the total amount will be for $32.40, not $30.00 with
$2.40 of tax included.
The tax_amount and the amount must be in the same currency.
Optional Decimal (15) Table 20 Preapproved Payment Offer-Level Fields (Continued)
Offer-Level Field Description Required/
Optional
Data Type
& Length
Table 21 Preapproved Payment Reply Fields
Reply Field Description Data Type
& Length client_lib_version Information about the client library used to request the
transaction.
String (50)
ics_rcode One-digit code that indicates whether the entire request was successful. The field will contain one of the following values:
-1: An error occurred
0: The request was declined
1: The request was successful
Integer (1)
ics_rflag One-word description of the result of the entire request. See Table 22, page 99 for a list of possible values.
String (50)
ics_rmsg Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler.
String (255)
paypal_preapproved_
payment_desc
Value of the paypal_mp_desc field you provided when creating the billing agreement button.
String (no length limit) paypal_preapproved_
payment_exchange_rate
Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer's non-primary currency.
If the customer chooses to pay in a currency other than the non-primary currency, the conversion occurs in the customer's account.
String (15)
paypal_preapproved_
payment_fee_amount
PayPal fee amount charged for the transaction. String (15)
paypal_preapproved_
payment_mp_max
Monthly maximum payment amount. String (15)
paypal_preapproved_
payment_mp_status
Current status of the billing agreement. This field will contain one of the following values:
Active
Canceled
String (9)
paypal_preapproved_
payment_payer
Customer's PayPal account identifier (customer's email address).
String (no length limit) paypal_preapproved_
payment_payer_business
Customer's business name if the customer has a PayPal Business or Premier account.
String (no length limit) paypal_preapproved_
payment_payer_country
Customer's country of residence. String (no
length limit) paypal_preapproved_
payment_payer_id
PayPal-generated unique customer ID. String (no length limit) paypal_preapproved_
payment_payer_name
Customer's name. String (no
length limit) paypal_preapproved_
payment_payer_status
Status of the customer's email address. This field will contain one of the following values:
verified: Customer’s PayPal account is Verified
unverified: Customer’s PayPal account is Unverified
String (10)
paypal_preapproved_
payment_payment_date
PayPal's timestamp for the payment. Example: 18:30:30 Jan 1, 2000 PST.
String (20)
paypal_preapproved_
payment_payment_gross_
amount
The final amount charged including any shipping or taxes from your PayPal profile.
String (15) Table 21 Preapproved Payment Reply Fields (Continued)
Reply Field Description Data Type
& Length
paypal_preapproved_
payment_payment_status
Status of the preapproved payment. This field will contain one of the following values:
Completed
Pending (see reasons in paypal_preapproved_
payment_pending_reason below)
Indicates whether the payment is instant or delayed. This field will contain one of the following values:
echeck
instant
String (7)
paypal_preapproved_
payment_pending_reason
Reason a payment is pending if paypal_preapproved_
payment_payment_status=Pending. This field will contain one of the following values:
address: Customer did not include a confirmed shipping address, and you have your Payment Receiving Preferences set to manually accept or deny each of these payments.
echeck: Electronic check has not cleared yet.
intl: You hold a non-U.S. account and do not have a withdrawal method. You must manually accept or deny this payment from your PayPal Account Overview.
multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept the payment. You must manually accept or deny the payment.
other: Payment is pending for a reason other than the other reasons listed here. Contact PayPal Customer Service.
unilateral: The payment was made to an email address that is not yet registered or confirmed.
upgrade: Payment was made via credit card and you must upgrade your account to Business or Premier status to receive the funds. You could also get this status because you have reached the monthly limit for transactions on your account.
verify: You are not yet verified. You must verify your
String (14) Table 21 Preapproved Payment Reply Fields (Continued)
Reply Field Description Data Type
& Length
paypal_preapproved_
payment_rcode
One-digit code that indicates whether the ics_paypal_
preapproved_payment request was successful. The field will contain one of the following values:
-1: An error occurred
0: The request was declined
1: The request was successful
Integer (1)
paypal_preapproved_
payment_rflag
One-word description of the result of the ics_paypal_
preapproved_payment request. See Table 22, page 99 for a list of possible values.
String (50)
paypal_preapproved_
payment_rmsg
Message that explains the reply flag paypal_preapproved_
payment_rflag. Do not display this message to the customer, and do not use this field to write an error handler.
String (255)
paypal_preapproved_
payment_settle_amount
Amount deposited in your PayPal account after a currency conversion.
String (15)
paypal_preapproved_
payment_tax_amount
Tax charged on the transaction. String (15)
paypal_preapproved_
payment_time
Time of the preapproved payment request. The format is YYYY-MM-DDThhmmssZ. For example, 2003-08-11T224757Z is equalto August 11, 2003, at 10:47:57 P.M.
The T separates the date and the time. The Z indicates
Reference number for the transaction that you use to reconcile your transactions.
String (60)
paypal_preapproved_
payment_transaction_id
PayPal's unique transaction ID for the payment. String (no length limit) paypal_preapproved_
payment_transaction_type
Type of PayPal payment. This field will contain the value mercht-pmt.
request_id Unique identifier for the request generated by the client. String (26) request_token Request token data created by CyberSource for each reply.
The field is an encoded string that contains no confidential information such as an account or card verification number.
The string can contain a maximum of 256 characters.
For more information, see the information about request tokens in Getting Started with CyberSource Advanced.
String (256) Table 21 Preapproved Payment Reply Fields (Continued)
Reply Field Description Data Type
& Length
Reply Flags
The following table describes the rflags for ics_paypal_preapproved_payment.
Canceling or Updating a Billing Agreement
You can cancel a billing agreement or update a billing agreement with a new description of the goods and services. To do either of these, use ics_paypal_preapproved_update.
You may not update the maximum amount for a billing agreement.
To request the service, send a request with ics_applications=ics_paypal_
preapproved_update. Do not include any other ICS services in the request. See Appendix B, "Examples for the SCMP API," on page 128 for example requests and replies.
You can view the details of a billing agreement in the Business Center. See "Billing Agreements," page 12 for more information.
Table 22 Preapproved Payment Reply Flags Reply Flag Description
DINVALIDDATA Data provided is not consistent with the request. For example, you requested a product with negative cost.
DMISSINGFIELD The request is missing a required field.
ESYSTEM System error. See the documentation for your CyberSource client (SDK) for important information about how to handle system errors and retries.
ETIMEOUT The request timed out.
SOK The transaction was successful.
Request-Level Fields
The following table lists the request-level fields for ics_paypal_preapproved_update.
The service uses no offer-level fields.
Reply Fields
The following table lists the reply fields for ics_paypal_preapproved_update.
Table 23 Billing Agreement Update Request-Level Fields
Request-Level Field Description Required/
Optional
Data Type
& Length ics_applications ICS services to process for the request. Required String (255) merchant_id Your CyberSource merchant ID. Use the same merchant_
id for evaluation, testing, and production.
Required String (30)
merchant_ref_number Order reference or tracking number that you provided in the request. See the information about order tracking in Getting Started with CyberSource Advanced.
Required String (50)
paypal_mp_desc Description of the goods or services associated with the billing agreement.
Optional String (no length limit) paypal_mp_id Billing agreement identifier (the mp_id) that you received
from PayPal.
Required String (19)
paypal_mp_status Set this field to Canceled to cancel the billing
agreement. The value is case sensitive, so make sure to set it exactly as shown here.
Optional String (8)
timeout Number of seconds the system waits before the transaction times out. The default is 110 seconds.
Optional Positive integer (3)
Table 24 Billing Agreement Update Reply Fields
Request Field Description Data Type
& Length client_lib_version Information about the client library used to request the
transaction.
String (50)
ics_rcode One-digit code that indicates whether the entire request was successful. The field will contain one of the following values:
-1: An error occurred
0: The request was declined
1: The request was successful
Integer (1)
ics_rflag One-word description of the result of the entire request. See Table 25, page 102 for a list of possible values.
String (50)
ics_rmsg Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler.
String (255)
merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters.
String (50)
paypal_preapproved_
update_desc
Value of the paypal_mp_desc field you provided when creating the billing agreement button.
String (no length limit) paypal_preapproved_
update_mp_max
Monthly maximum payment amount. Decimal
(15) paypal_preapproved_
update_mp_status
Current status of the billing agreement. This field will contain one of the following values:
Active
Canceled
String (9)
paypal_preapproved_
update_payer
Customer's PayPal account identifier (customer's email address).
String (no length limit) paypal_preapproved_
update_payer_business
Customer's business name if the customer has a PayPal Business or Premier account.
String (no length limit) paypal_preapproved_
update_payer_country
Customer's country of residence. String (no
length limit) paypal_preapproved_
update_payer_id
PayPal-generated unique customer ID. String (no length limit) paypal_preapproved_
update_payer_name
Customer's name. String (no
length limit) paypal_preapproved_
update_payer_status
Status of the customer's email address. This field will contain one of the following values:
verified: Customer’s PayPal account is Verified
unverified: Customer’s PayPal account is Unverified
String (10)
paypal_preapproved_
update_rcode
One-digit code that indicates whether the ics_paypal_
preapproved_update request was successful. The field will contain one of the following values:
-1: An error occurred
0: The request was declined
1: The request was successful
Integer (1)
paypal_preapproved_
update_rflag
One-word description of the result of the ics_paypal_
preapproved_update request. See Table 25, page 102 for a list of possible values.
String (50)
paypal_preapproved_
update_rmsg
Message that explains the reply flag paypal_preapproved_
update_rflag. Do not display this message to the customer, and do not use this field to write an error handler.
String (255) Table 24 Billing Agreement Update Reply Fields (Continued)
Request Field Description Data Type
& Length
Reply Flags
The following table describes the rflags for ics_paypal_preapproved_update.
Processing a Credit
Use ics_paypal_credit to perform a credit for a regular payment or a preapproved payment. For general information about refunding PayPal payments, see "PayPal Credits," page 13.
paypal_preapproved_
update_time
Time of the billing agreement update request. The format is YYYY-MM-DDThhmmssZ. For example, 2003-08-11T224757Z is equalto August 11, 2003, at 10:47:57 P.M.
The T separates the date and the time. The Z indicates UTC.
Date and time (20)
paypal_preapproved_
update_trans_ref_no
Reference number for the transaction that you use to reconcile
Reference number for the transaction that you use to reconcile