After the customer has accepted the billing agreement, you may process preapproved payments according to the agreement. Use payPalPreapprovedPaymentService to process each payment. In the payPalPreapprovedPaymentService_mpID 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.
To request the service, set payPalPreapprovedPaymentService_run=true. See Appendix A, "Examples for the Simple Order API," on page 110 for example requests and replies.
The only other ICS service that you may call in conjunction with
payPalPreapprovedPaymentService is taxService. See the Tax Calculation Implementation Guide.
payPalButtonCreateReply_
unencryptedFormData
Unencrypted version of the button. String (no
length limit) reasonCode Numeric value corresponding to the result of the overall request.
See "Reason Codes," page 70 for a list of possible values.
Integer (5)
requestID Unique identifier for the request. String (26)
requestToken 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.
String (256) Table 5 Reply Fields for Button Create (Continued)
Reply Field Description Data
Type &
Length
Request Fields
The following table lists the request fields for processing a preapproved payment.
Table 6 Preapproved Payment Request Fields
Request Field Description Required
/
Optional
Data Type &
Length
billTo_city City of the billing address. Required String (50)
billTo_country Country of the billing address. Use the two-character ISO codes. See the Support Center for a list of codes.
Required String (2)
billTo_email Customer’s email address, including the full domain name (for example, [email protected]).
Optional String (255)
billTo_firstName Customer’s first name. Required String (60)
billTo_lastName Customer’s last name. Required String (60)
billTo_postalCode 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)
billTo_state State or province of the billing address. Use the two-character codes. See the Support Center for a list of valid codes.
Required if country is U.S. or Canada
String (2)
item_#_productCode Type of product. The default value is default. See
"Product Codes," page 152 for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_quantity, item_#_productName, and item_#_productSKU fields are required.
Optional String (30)
item_#_productName Product’s name. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.
See description
String (30)
item_#_productSKU Product’s identifier code. Required if item_#_
productCode is NOT default, stored_value, or one of the values related to shipping and/or
See description
String (30)
item_#_quantity Quantity of the product being purchased. The default value is 1. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.
See description
Integer (10)
item_#_taxAmount Total tax to apply to the product. This value cannot be negative.
The item_#_taxAmount field is additive. For example, if you send one item with unitPrice of
$10.00 and taxAmount of $0.80, and you send another item with unitPrice of $20.00 and
taxAmount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included.
The item_#_taxAmount and the item_#_unitPrice must be in the same currency.
Optional String (15)
item_#_unitPrice Per-item price of the product. You must include either this field or purchaseTotals_grandTotalAmount in your request. See the information about items 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
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 details, see the information about partial authorizations in Credit Card Services Using the Simple Order API.
Optional String (26)
merchantID Your CyberSource merchant ID. Use the same merchantID for evaluation, testing, and production.
Required String (30)
merchantReferenceCode Merchant-generated order reference or tracking number. See the information about order tracking in Getting Started with CyberSource Advanced.
Required String (50)
paypal_customer_email Customer’s email address, including the full domain name (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 the purchased item. Optional String (no
length limit) Table 6 Preapproved Payment Request Fields (Continued)
Request Field Description Required
/
Optional
Data Type &
Length
paypal_item_number Reference number of the 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) 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)
payPalPreapproved PaymentService_mpID
Billing agreement identifier (the mp_id). Required String (19)
payPalPreapproved PaymentService_run
Set to true to request
payPalPreapprovedPaymentService.
Required String (5)
purchaseTotals_currency Currency used for the order. PayPal currently accepts orders that use USD, CAD, EUR, GBP, or JPY only.
Required String (5)
purchaseTotals_
grandTotalAmount
Grand total for the order. You must include either this field or item_#_unitPrice in your request. See the information about items and grand totals in Getting Started with CyberSource Advanced.
See description
String (15) Table 6 Preapproved Payment Request Fields (Continued)
Request Field Description Required
/
Optional
Data Type &
Length
Reply Fields
The following table lists the reply fields for processing a preapproved payment.
Table 7 Preapproved Payment Reply Fields
Reply Field Description Data
Type &
Length decision Summarizes the result of the overall request. The field can
contain one of the following values:
ACCEPT
ERROR
REJECT
String (6)
invalidField_0...N Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced.
String (100)
merchantReferenceCode 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)
missingField_0...N Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. See the information about missing and invalid fields in Getting Started with CyberSource Advanced.
String (100)
payPalPreapproved PaymentReply_desc
Value of the paypal_mp_desc field you provided when creating the billing agreement button.
String (no length limit) payPalPreapproved
PaymentReply_exchangeRate
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)
payPalPreapproved PaymentReply_feeAmount
PayPal fee amount charged for the transaction. String (15)
payPalPreapproved PaymentReply_mpMax
Monthly maximum payment amount. String (15)
payPalPreapproved PaymentReply_mpStatus
Current status of the billing agreement. This field will contain one of the following values:
Active
Canceled
String (9)
payPalPreapproved PaymentReply_payer
Customer's PayPal account identifier (customer's email address).
String (no length limit) payPalPreapproved
PaymentReply_payerBusiness
Customer's business name if the customer has a PayPal Business or Premier account.
String (no length limit) payPalPreapproved
PaymentReply_payerCountry
Customer's country of residence. String (no
length limit) payPalPreapproved
PaymentReply_payerID
PayPal-generated unique customer ID. String (no length limit) payPalPreapproved
PaymentReply_payerName
Customer's name. String (no
length limit) payPalPreapproved
PaymentReply_payerStatus
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)
payPalPreapproved
PaymentReply_paymentDate
PayPal's timestamp for the payment. Example:
18:30:30 Jan 1, 2000 PST.
String (20)
payPalPreapproved PaymentReply_
paymentGrossAmount
The final amount charged including any shipping or taxes from your PayPal profile.
String (15)
payPalPreapproved
PaymentReply_paymentStatus
Status of the preapproved payment. This field will contain one of the following values:
Completed
Indicates whether the payment is instant or delayed. This field will contain one of the following values:
echeck
instant
String (7) Table 7 Preapproved Payment Reply Fields (Continued)
Reply Field Description Data
Type &
Length
payPalPreapproved
PaymentReply_pendingReason
Reason if payPalPreapprovedPaymentReply_
paymentStatus=Pending. This field will contain one of these 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 account before you can accept the payment.
String (14)
payPalPreapproved
PaymentReply_reasonCode
A numeric value corresponding to the result of the billing agreement update request. See "Reason Codes," page 70 for a list of possible values.
Integer (5)
payPalPreapproved
PaymentReply_reconciliationID
Reference number for the transaction that you use to reconcile your transactions.
String (60)
payPalPreapproved
PaymentReply_requestDateTime
Time of the preapproved payment request. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2003-08-11T22:47:57Z is equalto August 11, 2003, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC.
String (20)
payPalPreapproved
PaymentReply_settleAmount
Amount deposited in your PayPal account after a currency conversion.
String (15)
payPalPreapproved PaymentReply_taxAmount
Tax charged on the transaction. String (15)
Table 7 Preapproved Payment Reply Fields (Continued)
Reply Field Description Data
Type &
Length