SetCustomerBillingAgreement API Operation (NVP)

Initiates the creation of a billing agreement.

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

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

SetCustomerBillingAgreement Request Fields

Field Description
METHOD (Required) Must be SetCustomerBillingAgreement.

RETURNURL (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 (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 (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 (Optional) Sets the Custom Payment Page Style for payment pages associated with this button/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 chose when adding or editing the page style in your PayPal account. Character length and limitations: 30 single-byte alphabetic characters
HDRIMG (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 requires that you provide an image that is stored on a secure (https) server. Character length and limitations: 127 single-byte alphanumeric characters
HDRBORDERCOLOR
(deprecated)
(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
HDRBACKCOLOR
(deprecated)
(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
PAYFLOWCOLOR (Optional) Sets the background color for the payment page. Character length and limitation: 6-character HTML hexadecimal color code in ASCII
EMAIL (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
L_BILLINGTYPEn (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.
BILLINGTYPE Type of billing agreement for reference transactions. You must have permission from PayPal to use this field. For reference transactions, 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.
Other defined values are not valid.
L_BILLINGAGREEMENTDESCRIPTIONn 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
L_PAYMENTTYPEn (Optional) Type of PayPal payment you require for the billing agreement. Value is:
  • Any
  • InstantOnly
Note: For recurring payments, this field is ignored.
L_BILLINGAGREEMENTCUSTOMn (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

SetCustomerBillingAgreement Response Fields

Field Description
TOKEN 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