BAUpdate API Operation (NVP)

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 becomes valid and remains valid until it is 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 referenced is 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 legacy systems.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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

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