Overview

JavaScript v3

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• JavaScript v2

Integrating Shipping Module

The PayPal shipping module presents shipping details to a buyer during the PayPal flow. The merchant has several ways to determine how shipping addresses and shipping options are handled. The server-side shipping callbacks allow you to update the shipping and order amount information as buyers make changes on the PayPal review page.

Buyers can use the shipping module to specify the shipping address and shipping options on the PayPal paysheet. PayPal sends a callback to the merchant's URL with the updated shipping information (buyer’s address, state, city, country code, and zip code) using the server-side shipping callbacks. In response, the merchant can send PayPal the shipping options and updated order cost amounts.

To include Shipping Module in your integration, set the server side shipping callback URL as shown below. For more information, see the Integration code samples section, below.

// Add shippingCallbackUrl createPayment() request options
createPaymentRequestOptions.shippingCallbackUrl = "https://www.example.com/"

Callback Events

The shipping module supports the following callback events:

• onShippingAddressChange: This event occurs when the review page loads for the first time and when the buyer changes their shipping address. We recommend subscribing only to onShippingAddressChange, as this requires you to respond with all shipping options and amounts calculated on the initial callback, reducing delays and the number of requests.
• onShippingOptionsChange: This event occurs when the buyer selects new shipping options. Subscribe to this if you want to be notified or need to recalculate amounts when a selected shipping option changes for the current address.

onShippingAddressChange

Updates an order to add shipping address to purchase unit (or) replace the shipping address
//Request
curl -v -X PATCH 'https://api-m.sandbox.paypal.com/v2/checkout/orders/:order_id'
-H "Content-Type: application/json" 
-H "Authorization: Bearer ACCESS_TOKEN" 
-d '[
    {
        "op": "replace",
        "path": "/purchase_units/@reference_id=='PUHF'/shipping/address",
        "value": {
            "address_line_1": "2211 N First Street",
            "address_line_2": "Building 17",
            "admin_area_2": "San Jose",
            "admin_area_1": "CA",
            "postal_code": "95131",
            "country_code": "US"
        }
    }
]'

• Validate that you support the shipping method.
• Update shipping costs.
• Change the line items in the cart.
• Inform the buyer that you don't support their shipping method.

onShippingOptionsChange

Updates an order to add shipping options to purchase unit.
//Request
curl -v -X PATCH 'https://api-m.sandbox.paypal.com/v2/checkout/orders/:order_id'
 -H 'Authorization: Bearer ACCESS_TOKEN
 -H 'Content-Type: application/json'
 -d '[
    {
        "op": "add",
        "path": "/purchase_units/@reference_id=='PUHF'/shipping/options",
        "value": [
            {
                "id": "STORE0002012345202",
                "label": "Ground Shipping",
                "type": "SHIPPING",
                "amount": {
                    "currency_code": "USD",
                    "value": "10.00"
                },
                "selected": true
            }
        ]
    }
]'

Domain registration

In order to use server-side shipping callbacks with PayPal, you'll need to register any domains you plan to use as the shippingCallbackUrl. You can do this through the Braintree control panel using the instructions below. You will have to do this in both your sandbox and production environments.

Rules for domain names

A domain name:

• Must not start with a scheme (e.g. "https://").

• Must be between 4 and 255 characters.

• Cannot contain spaces or wildcards (*).

• Can consist of a top-level domain, a second-level domain, and 0 or more subdomains etc. a.b.example.com where example is the top-level domain, com is the second-level domain, and a and b are subdomains.

• The top-level domain must consist of 2 to 63 letters.

• Each subdomain and the second-level domain must consist of 1 to 63 alphanumeric characters and or hyphens.

• Each subdomain and the second-level domain can not start or end with a hyphen.

• The top-level domain, second-level domain, and the subdomains must be separated by a dot(.).

• Can end with a trailing dot.

Sandbox environment

Register your sandbox domain name in the Braintree Control Panel:

1. Log into your sandbox Control Panel

2. Click on the gear icon in the top right corner

3. Click Account Settings from the drop-down menu

4. Scroll to the Payment Methods section

5. Next to PayPal, click the Options link

6. Client the View Domain Names button

7. Enter the domain of your return page in the Specify Your Domain Names section.

8. Click Add Domain Names button

Production environment

Register your production domain name in the Braintree Control Panel:

1. Log into your production Control Panel

2. Click on the gear icon in the top right corner

3. Click Account Settings from the drop-down menu

4. Scroll to the Payment Methods section

5. Next to PayPal, click the Options link

6. Client the View Domain Names button

7. Enter the domain of your return page in the Specify Your Domain Names section.

8. Click Add Domain Names button