Address Handling (U.S. Merchants Only)
Last updated: Sept 19th, 1:48am
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.
Various HTML variables and PayPal account settings determine whether people can change, add, or override billing and shipping addresses during checkout.
| Decision | Variable or Setting to Use |
|---|---|
| Do you fill out the address automatically for buyers? | Use address variables to specify the buyer's address. PayPal fills out the address automatically on the checkout pages. |
| Do you let buyers override their PayPal addresses? | Use the address_override variable.
|
| Do you require buyers to have confirmed addresses? | Use the Block payments from U.S. users who do not provide a Confirmed Address setting in your Account Profile.
To learn how to block payments, see Block certain kinds of payments in the Merchant setup and administration guide. |
| How do you prompt buyers for shipping addresses? | Use the no_shipping variable.
Allowable values are:
|
In the following diagram, letters A through L represent results of decisions that PayPal makes about handling buyers' addresses during checkout. Decisions are based on the preceding HTML variables in your button code and settings in your Account Profile.
Read these topics to learn more:
- Address Handling with PayPal Account Optional Turned On
- Address Handling With PayPal Account Optional Turned Off
Address Handling with PayPal Account Optional Turned On
If you enabled the PayPal Account Optional feature in your account profile, learn how PayPal handles buyers' addresses during checkout. In the previous image, the letters A through L indicate PayPal's decisions.
With PayPal Account Optional turned on, buyers can pay by debit card or credit card without signing up for PayPal accounts. PayPal Account Optional is turned on by default. For more information, see PayPal Account Optional.
Result A
The billing page displays the address filled out automatically. If buyers modify the address and submit the page, PayPal returns an error saying that the address cannot be modified. The Shipping Address on the Review Your Payment page displays this address. Buyers cannot change the shipping address.
If the automatically filled-out address is invalid, PayPal displays an error page that indicates the buyer cannot proceed because the merchant provided an invalid address.
Results B, C, or D
The billing page displays the address filled out automatically. Buyers can modify the billing address. The Shipping Address on the Review Your Payment page displays this address. Buyers cannot change the shipping address.
If the automatically filled-out address is invalid, PayPal fills out the billing page automatically, and the buyer can modify it. PayPal does not display Shipping Address on the Review Your Payment page.
Result E
The billing page displays the address filled out automatically. Buyers can modify the billing address. The Shipping Address on the Review Your Payment page displays the address from the billing page. Buyers cannot change the shipping address. The shipping address always matches the billing address. Changes that buyers make to the billing address change the shipping address, too.
If the automatically filled-out address is invalid, PayPal fills out the billing page automatically, and the buyer can modify it.
Results F or H
The billing page displays the address filled out automatically. Buyers can modify the billing address. The Shipping Address on the Review Your Payment page displays the address from the billing page. Buyers can change the shipping address independently of the billing address.
If the automatically filled-out address is invalid, PayPal fills out the billing page automatically, and the buyer can modify it.
Result G
The billing page displays the address filled out automatically. Buyers can modify the billing address. PayPal does not display Shipping Address on the Review Your Payment page.
Result I
The Shipping Address on the Review Your Payment page displays the address that buyers enter on the billing page. Buyers cannot change the shipping address. The shipping address always matches the billing address. Changes that buyers make to the billing address change the shipping address, too.
Results J and L
The Shipping Address on the Review Your Payment page displays the address that buyers enter on the billing page. Buyers can change the shipping address independently of the billing address.
Address Handling With PayPal Account Optional Turned Off
If PayPal Account Optional is turned off in your Account profile, read this section. It describes how PayPal handles buyer's addresses during checkout. The following letters "A" through "L" represent the results of decisions that PayPal makes, as illustrated in the figure above.
With PayPal Account Optional turned off, buyers without PayPal accounts must sign up for PayPal accounts before they complete their payments. PayPal Account Optional is turned on by default. If you want the address handling described in this section, turn off PayPal Account Optional. For more information, see PayPal Account Optional.
Result A
If the automatically filled out address is confirmed, the Shipping Address on the Review Your Payment page displays the address filled out. The buyer cannot change the shipping address.
If the automatically filled out address is unconfirmed, PayPal displays the Add Credit Card or Debit Card page with the filled out address as the billing address. The page displays a message that indicates the address must match the address on the buyer's account statement. If the specify a cancel_return URL, PayPal displays a Cancel button.
Results B, C, or D
The Shipping Address on the Review Your Payment page displays the automatically filled out address. Buyers cannot change the shipping address.
If the automatically filled out address is invalid, PayPal displays an error page that indicates the buyer cannot proceed because the merchant provided an invalid address.
Result E
If the automatically filled out address address is confirmed, PayPal displays Shipping Address on the Review Your Payment page with the automatically filled out address. Buyers can select or add another address. If buyers select Add New Address, PayPal displays the Add Credit Card or Debit Card page.
If the automatically filled out address is unconfirmed, PayPal displays the Add Credit Card or Debit Card page filled in automatically with the unconfirmed address. If there is no confirmed address in the buyer's Account Profile, the same behavior occurs
Results F or H
The Shipping Address on the Review Your Payment page displays the automatically filled out address. Buyers can select or add another address.
If the automatically filled out address address is invalid, PayPal discards that address and displays the address in the Account Profile, if available. Buyers can select another address or add one directly in the Review Your Payment page.
Result I
If buyers have confirmed addresses in their Account Profiles, PayPal displays the Review Your Payment page. Buyers can select another confirmed address or add an address. If buyers select Add New Address, PayPal displays the Add Credit Card or Debit Card page.
If buyers have no confirmed addresses in their Account Profiles, PayPal displays the Add Credit Card or Debit Card page.
Results J or L
The Shipping Address on the Review Your Payment page displays the buyer's primary address. Buyers can select another address or add one directly in the Review Your Payment page.