SetCustomerBillingAgreement API Operation (SOAP)

Initiates the creation of a billing agreement.

This API operation has been deprecated starting with API version 54.0 or later.

Important: If you use Express Checkout with API version 54.0 or later, do not use the SetCustomerBillingAgreement and GetBillingAgreementCustomerDetails API operations for billing agreements. Instead, to set up a billing agreement, use the SetExpressCheckout (NVP, SOAP) API operation and set the amount to zero. Call the GetExpressCheckoutDetails (NVP, SOAP) API operation to obtain information about the buyer and the buyer's checkout status. Then use the CreateBillingAgreement (NVP, SOAP) API operation to create the billing agreement. See Billing agreements.

SetCustomerBillingAgreement Request Message

Note: Only the fields described in this documentation are available for use.

Note: Only the fields described in this documentation are available for use.

SetCustomerBillingAgreement Request Fields

Field

Description

BillingAgreement Details

ns:BillingAgreementDetailsType

(Required) Details of the billing agreement such as the billing type, billing agreement description, and payment type.

ReturnURL

xs:string

(Required) URL to which the buyer's browser is returned after choosing to pay with PayPal.

Note: PayPal recommends that the value be the final review page on which the buyer confirms the billing agreement.

Character length and limitations: no limit

CancelURL

xs:string

(Required) URL to which the customer is returned if he does not approve the use of PayPal to pay you.

Note: PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: no limit

LocaleCode

xs:string

(Optional) Locale of pages displayed by PayPal during checkout. It is one of the following values supported by PayPal:


  • AU— Australia

  • AT— Austria

  • BE— Belgium

  • BR— Brazil

  • CA— Canada

  • CH— Switzerland

  • CN— China

  • DE— Germany

  • ES— Spain

  • GB— United Kingdom

  • FR— France

  • IT— Italy

  • NL— Netherlands

  • PL— Poland

  • PT— Portugal

  • RU— Russia

  • US— United States

  • The following 5-character codes are also supported for languages in specific countries:


    • da_DK— Danish (for Denmark only)

    • he_IL— Hebrew (all)

    • id_ID— Indonesian (for Indonesia only)

    • ja_JP— Japanese (for Japan only)

    • no_NO— Norwegian (for Norway only)

    • pt_BR— Brazilian Portuguese (for Portugal and Brazil only)

    • ru_RU— Russian (for Lithuania, Latvia, and Ukraine only)

    • sv_SE— Swedish (for Sweden only)

    • th_TH— Thai (for Thailand only)

    • zh_CN— Simplified Chinese (for China only)

    • zh_HK— Traditional Chinese (for Hong Kong only)

    • zh_TW— Traditional Chinese (for Taiwan only)

Note: If the locale code is not supplied or the supplied value is not one of the above-listed values, it is defaulted by PayPal. The default is determined using information about the current merchant, user, and other information for the session.

Character length and limitations: A 2-character country code or 5-character code as specified above.

PageStyle

xs:string

(Optional) Sets the Custom Payment Page Style for payment pages associated with this button/link. This value corresponds to the HTML variable page_stylefor customizing payment pages. The value is the same as the Page Style Name you chose when adding or editing the page style in your PayPal account.

Character length and limitations: 30 single-byte alphabetic characters

cpp-header-image

xs:string

(Optional) A URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server.

Character length and limitations: 127 single-byte alphanumeric characters

cpp-header-border
(deprecated)

xs:string

(Optional) Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high.

Character length and limitations: 6-character HTML hexadecimal color code in ASCII

cpp-header-back-color
(deprecated)

xs:string

(Optional) Sets the background color for the header of the payment page. By default, the color is white.

Character length and limitation: 6-character HTML hexadecimal color code in ASCII

cpp-payflow-color

xs:string

(Optional) Sets the background color for the payment page.

Character length and limitation: 6-character HTML hexadecimal color code in ASCII

BuyerEmail

ns:EmailAddressType

(Optional) Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership signup portion of the PayPal login page.

Character length and limit: 127 single-byte alphanumeric characters

BillingAgreementDetails Fields

Field

Description

BillingType

ns:BillingCodeType

(Required) Type of billing agreement. For recurring payments, this field must be set to RecurringPayments. In this case, you can specify up to ten billing agreements. Other defined values are not valid.

Type of billing agreement for reference transactions. You must have permission from PayPal to use this field. This field must be set to one of the following values:

  • MerchantInitiatedBilling- PayPal creates a billing agreement for each transaction associated with buyer. You must specify version 54.0 or higher to use this option.

  • MerchantInitiatedBillingSingleAgreement- PayPal creates a single billing agreement for all transactions associated with buyer. Use this value unless you need per-transaction billing agreements. You must specify version 58.0 or higher to use this option.

BillingAgreement Description

xs:string

Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. PayPal recommends that the description contain a brief summary of the billing agreement terms and conditions. For example, buyer is billed at "9.99 per month for 2 years."

Character length and limitations: 127 single-byte alphanumeric characters

PaymentType

ns:MerchantPullPaymentCodeType

(Optional) Type of PayPal payment you require for the billing agreement. Value is:

  • Any

  • InstantOnly

Note: For recurring payments, this field is ignored.

BillingAgreement Custom

xs:string

(Optional) Custom annotation field for your own use.

Note: For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes

SetCustomerBillingAgreement Response Message

Note: Only the fields described in this documentation are available for use.

SetCustomerBillingAgreement Response Fields

Field

Description

Token

xs:string

A unique time-stamped token, which uniquely identifies this transaction in subsequent API calls.

Note: the token expires after three hours.

Character length and limitations: 20 single-byte characters

Additional information

Feedback