BAUpdate API Operation (NVP)

API

Last updated: Sept 18th, 5:14pm

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

Updates or deletes a billing agreement.

BAUpdate Request Message

BAUpdate Request Fields

Field	Description
`METHOD`	(Required) Must be `BillAgreementUpdate`.
`REFERENCEID`	(Required) An ID, such as a billing agreement ID or a reference transaction ID that is associated with a billing agreement.
`BILLINGAGREEMENTSTATUS`	(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the value `Canceled`. Note: If you do not pass the value `Canceled`, `BAUpdate` returns the buyer's latest billing address.
`BILLINGAGREEMENTDESCRIPTION`	(Optional) 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 will be billed at “9.99 per month for 2 years.” Character length and limitations: 127 single-byte alphanumeric characters
`BILLINGAGREEMENTCUSTOM`	(Optional) Custom annotation field for your own use. Note: For recurring payments, this field is ignored. Character length and limitations: 256 single-byte alphanumeric characters

BAUpdate Response Message

BAUpdate Response Fields

Field	Description
`BILLINGAGREEMENTID`	Identification number of the billing agreement. When the buyer approves the billing agreement, it remains valid until canceled by the buyer. Note: For reference transactions, you can pass a billing agreement ID in the `ReferenceID` request field. Also, a billing agreement ID is returned in the transaction response when the transaction references a billing agreement. Character length and limitations: 19 single-byte alphanumeric characters
`BILLINGAGREEMENTDESCRIPTION`	Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. Character length and limitations: 127 single-byte alphanumeric characters
`BILLINGAGREEMENTCUSTOM`	Custom annotation field for your own use. Character length and limitations: 256 single-byte alphanumeric characters
`BILLINGAGREEMENTSTATUS`	(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the value `Canceled`. Note: If you do not pass the value `Canceled`, `BAUpdate` returns the buyer's latest billing address.
`BILLINGAGREEMENTMAX`	Maximum amount for this billing agreement. Note: This field only has a value if the buyer signed up for PayPal using Preapproved Payments; it is included for backwards compatibility with deprecated systems. Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (`.`), and the optional thousands separator must be a comma (`,`). Some currencies do not allow decimals. For details, see the currency codes page.
`BILLINGADDRESS`	Customer's billing address. If the customer has stored a credit card in his/her account then the billing address of the credit card is returned; otherwise the customer's primary address is returned.

Payer Information Fields

Field	Description
`EMAIL`	Email address of buyer. Character length and limitations: 127 single-byte characters
`PAYERID`	Unique PayPal Customer Account identification number. Character length and limitations: 17 single-byte alphanumeric characters
`PAYERSTATUS`	Status of buyer. It is one of the following values: `verified` `unverified` Character length and limitations: 10 single-byte alphabetic characters
`COUNTRYCODE`	Buyer's country of residence in the form of ISO standard 3166 2-character country codes. Character length and limitations: 2 single-byte characters
`PAYERBUSINESS`	Buyer's business name. Character length and limitations: 127 single-byte characters

Payer Name Fields

Field	Description
`SALUTATION`	Buyer's salutation. Character length and limitations: 20 single-byte characters
`FIRSTNAME`	Buyer's first name. Character length and limitations: 64 single-byte characters
`MIDDLENAME`	Buyer's middle name. Character length and limitations: 64 single-byte characters
`LASTNAME`	Buyer's last name. Character length and limitations: 64 single-byte characters
`SUFFIX`	Buyer's suffix. Character length and limitations: 12 single-byte characters

Bill To Address Fields

Field	Description
`BILLINGNAME`	Billing name associated with this billing address. Character length and limitations: 32 single-byte characters
`STREET`	First billing street address. Character length and limitations: 100 single-byte characters
`STREET2`	Second billing street address. Character length and limitations: 100 single-byte characters
`CITY`	Name of billing city. Character length and limitations: 40 single-byte characters
`STATE`	Billing state or province. Required for U.S. addresses only. Character length and limitations: 40 single-byte characters
`ZIP`	U.S. billing ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters
`COUNTRYCODE`	Billing country code. Character length and limitations: 2 single-byte characters

PayeeInfoType Fields

Information about the merchant or the owner of the billing agreement.

Field Description

Field	Description
`PAYEEEMAIL`	Email address of the merchant or owner of the billing agreement. Character length and limitations: 127 single-byte characters
`PAYEEID`	Unique merchant account identification number. Character length and limitations: 17 single-byte alphanumeric characters

PAYEEEMAIL

Email address of the merchant or owner of the billing agreement.

Character length and limitations: 127 single-byte characters

PAYEEID

Unique merchant account identification number.

Character length and limitations: 17 single-byte alphanumeric characters

Additional information

API error codes